From Trusted Tools to Capability Rules
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.
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
| Part | Values |
|---|---|
| Capability | fs_read, fs_write, shell, web_fetch, web_search, mcp, subagent, skill, power, context, diagnostics, sandbox_network |
| Effect | deny, ask, allow, evaluate (Approve for me) |
| Resolution | deny > ask > allow > evaluate |
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 toolsSettings | v3 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 |
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
- Compound shell commands are split.
a ; b,&&,||and pipes are each evaluated on their own. A rule fornpm *does not approve acurlchained after it. - Sub-agents are capped by the parent. In v2 a sub-agent's pre-approved tools ran unprompted. In v3 a sub-agent's
allownever grants more than the parent session allows, and headless runs deny the call.
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.
- Create
~/.kiro/settings/permissions.yamlwith a deny rule for secrets:rules: - capability: fs_read effect: deny match: ["**/.env", "**/.env.*", "**/*.pem"] - In a scratch directory, make a
.envfile, startkiro-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. - Run
/permissionsin the session and find where your rule appears. Then try removing the rule and asking again.
Reference: Permissions cheat sheet · Glossary
toolsSettings that need migrating?" I can inspect your ~/.kiro/agents/*.json and draft the equivalent rules. Anything unclear? Ask.