From Trusted Tools to Capability Rules

Lesson 1 · Kiro CLI v3 for v2 users. Time: 10 minutes. Tangible win: write a working permissions.yaml deny rule and predict how any rule set resolves.

In v2 you trusted tools: allowedTools, per-tool toolsSettings, /tools trust. In v3 you write rules about actions. This is the change most likely to break a migrated agent, so it comes first. Everything below is from the official Permissions and Migration guide pages.

Primary source Permissions — kiro.dev. Capabilities, effects, scopes, presets. About 15 minutes; read "Scopes" and "Pattern syntax" first.

The shape of a rule

A rule has a capability (what kind of operation), optional match and exclude globs, and an effect.

rules:
  - capability: shell
    match: ["npm *"]
    exclude: ["npm publish*"]
    effect: allow
PartValues
Capabilityfs_read, fs_write, shell, web_fetch, web_search, mcp, subagent, skill, power, context, diagnostics, sandbox_network
Effectdeny, ask, allow, evaluate (Approve for me)
Resolutiondeny > ask > allow > evaluate
Key insight

There is no precedence between scopes. User, workspace, agent and session rules are pooled, and the most restrictive effect wins. A workspace deny cannot be overridden by your user-level allow, and vice versa. In v2 you could think "more specific setting wins"; in v3 you cannot.

Translating v2

v2 toolsSettingsv3 rule
execute_bash.allowedCommands: ["^git status$"]shell, match git status, allow
execute_bash.deniedCommands: ["^rm -rf"]shell, match rm -rf*, deny
fs_read.deniedPaths: [".env"]fs_read, match .env, deny
fs_write.allowedPaths: ["src/**"]fs_write, match src/**, allow
Regex becomes glob

v2 patterns were regular expressions; v3 uses globs. Drop ^ and $, turn .* into *, and split alternations into multiple rules. In shell patterns only * works; ** and ? do not. In filesystem patterns * stays within one path component and ** crosses them.

Two things that surprise v2 users

Retrieval check

User scope has shell git * allow. Workspace scope has shell git push* deny. What happens to git push origin main?

Right. Scopes have no ranking; the most restrictive matching effect wins.

Scopes are pooled, not ranked. A matching deny always wins, so the push is denied.

With only shell npm * allow in place, you run npm test ; curl evil.example. What happens?

Right. Sub-commands are split and evaluated independently; curl matches no rule, so it falls to the default and prompts.

Kiro splits compound commands. npm test matches the allow, curl matches nothing and prompts.

How should v2 allowedCommands: ["^git (status|diff)$"] be migrated?

Right. Globs have no alternation in shell patterns, so list each command.

Shell globs support only *; there is no regex or alternation, so each command gets its own entry.

Practice

You have no ~/.kiro/settings/permissions.yaml yet, so this is a clean start. Kiro cannot write that file for you (it is a hard-denied path), so edit it yourself.

  1. Create ~/.kiro/settings/permissions.yaml with a deny rule for secrets:
    rules:
      - capability: fs_read
        effect: deny
        match: ["**/.env", "**/.env.*", "**/*.pem"]
  2. In a scratch directory, make a .env file, start kiro-cli, and ask it to read the file. The read should be refused. The policy hot-reloads, so no restart is needed after future edits.
  3. Run /permissions in the session and find where your rule appears. Then try removing the rule and asking again.

Reference: Permissions cheat sheet · Glossary

Ask me: "Which of my existing agents carry toolsSettings that need migrating?" I can inspect your ~/.kiro/agents/*.json and draft the equivalent rules. Anything unclear? Ask.