Permissions

Permissions give you declarative, auditable control over what the agent can do. Write one rule to allow npm * commands, and it applies everywhere -- no more pressing "y" on every shell invocation. Write one deny rule for .env files, and all read tools respect it simultaneously. Rules are portable across Kiro IDE and CLI because the same engine enforces them on both surfaces.

Each rule has four fields:

Effects resolve by restrictiveness: deny > ask > allow. A more permissive rule can never override a more restrictive one, regardless of which scope it comes from.

Workspace permissions are stored per-user outside the repository at ~/.kiro/workspace-roots/<hash(workspaceRoot)>/. A cloned repo cannot inject permission rules. Trust is something you configure on your own machine.

Create ~/.kiro/settings/permissions.yaml:

rules:
  - capability: shell
    effect: allow
    match:
      - git *
      - npm *
      - npx *
  - capability: fs_write
    effect: allow
    match:
      - src/**
      - tests/**
  - capability: fs_read
    effect: allow
  - capability: mcp
    effect: allow
    match:
      - my-server/*

For CI pipelines that need full tool access:

rules:
  - capability: all
    effect: allow

Without any configuration, the default agent policy allows:

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

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.

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, 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"

  # Allow a specific MCP server
  - capability: mcp
    effect: allow
    match:
      - "corp-tools/*"

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.