Skip to content

docs(customize): clarify agent permission rules - #11141

Merged
lambertjosh merged 7 commits into
Kilo-Org:mainfrom
singhvishalkr:docs/agent-permission-rules
Jun 17, 2026
Merged

docs(customize): clarify agent permission rules#11141
lambertjosh merged 7 commits into
Kilo-Org:mainfrom
singhvishalkr:docs/agent-permission-rules

Conversation

@singhvishalkr

Copy link
Copy Markdown
Contributor

Fixes #11106.

What changed:

  • Added a dedicated Agent Permissions page covering rule precedence, glob matching, workspace-relative file paths, shell command evaluation, sensitive file handling, and subagent delegation.
  • Linked the new page from the Customize navigation and overview.
  • Added a cross-link from Custom Subagents where bash permission rules are introduced.

Verification:

  • git diff --check
  • bun --version (blocked: Bun is not installed in this environment)

@vercel

vercel Bot commented Jun 11, 2026

Copy link
Copy Markdown

@singhvishalkr is attempting to deploy a commit to the Kilo Code Team on Vercel.

A member of the Team first needs to authorize it.

@lambertjosh lambertjosh left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this, just a few minor comments.

| `ask` | Prompt before running the matching tool call. |
| `deny` | Block the matching tool call. |

Rules can be written as a scalar action for the whole permission or as a pattern map:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we rephrase this using plainer language?

Comment thread packages/kilo-docs/pages/customize/agent-permissions.md
Comment thread packages/kilo-docs/pages/customize/agent-permissions.md

@lambertjosh lambertjosh left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry meant to request changes.

@kilo-code-bot

kilo-code-bot Bot commented Jun 16, 2026

Copy link
Copy Markdown
Contributor

Code Review Summary

Status: 1 Issue Found | Recommendation: Address before merge

Overview

Severity Count
WARNING 1
Issue Details (click to expand)

WARNING

File Line Issue
packages/kilo-docs/pages/getting-started/settings/auto-approving-actions.md 130 The "last matching rule wins" behavior described earlier confirms that examples with a catch-all "*" last override all preceding rules — ensure users understand this precedence.
Previously Flagged (carried forward from prior review)
File Line Issue
packages/kilo-docs/pages/customize/agent-permissions.md 25 YAML vs JSON clarification for agent files vs kilo.jsonc
packages/kilo-docs/pages/customize/agent-permissions.md N/A Rephrase introductory language to be plainer
Resolved in this update
File Line Issue
packages/kilo-docs/pages/customize/agent-permissions.md 29 edit pattern ordering fixed — "*": deny now before "*.md": allow per last-match-wins
packages/kilo-docs/pages/customize/agent-permissions.md 103 read pattern ordering fixed — "*": ask now before "docs/*": allow per last-match-wins
packages/kilo-docs/pages/customize/agent-permissions.md 107 edit pattern ordering fixed — "*": deny now before "*.md": allow per last-match-wins
Files Reviewed (1 file changed, 6 total)
  • packages/kilo-docs/pages/customize/agent-permissions.md — pattern ordering fixes applied
  • packages/kilo-docs/pages/getting-started/settings/auto-approving-actions.md — unchanged (1 issue carried forward)
  • packages/kilo-docs/pages/customize/custom-subagents.md — unchanged
  • packages/kilo-docs/pages/customize/index.md — unchanged
  • packages/kilo-docs/lib/nav/customize.ts — unchanged
  • packages/kilo-docs/pages/kiloclaw/development-tools/composio.md — unchanged

Fix these issues in Kilo Cloud

Previous Review Summaries (4 snapshots, latest commit 6e99eb0)

Current summary above is authoritative. Previous snapshots are kept for context only.

Previous review (commit 6e99eb0)

Status: 1 Issue Found | Recommendation: Address before merge

Overview

Severity Count
WARNING 1
Issue Details (click to expand)

WARNING

File Line Issue
packages/kilo-docs/pages/customize/agent-permissions.md 29 edit pattern ordering contradicts last-match-wins — "*.md": allow before "*": deny means .md files are denied
Previously Flagged (carried forward from prior review)
File Line Issue
packages/kilo-docs/pages/customize/agent-permissions.md 25 YAML vs JSON clarification for agent files vs kilo.jsonc
packages/kilo-docs/pages/customize/agent-permissions.md N/A Rephrase introductory language to be plainer
Resolved in this update
File Line Issue
packages/kilo-docs/pages/customize/agent-permissions.md 36 Rule Precedence section added to auto-approving-actions.md
packages/kilo-docs/pages/getting-started/settings/auto-approving-actions.md 130 Contradiction between last-match-wins and example ordering — all examples now use consistent ordering
Files Reviewed (6 files)
  • packages/kilo-docs/pages/customize/agent-permissions.md — 1 new issue (NEW FILE)
  • packages/kilo-docs/pages/getting-started/settings/auto-approving-actions.md — examples reordered, precedence section added
  • packages/kilo-docs/pages/customize/custom-subagents.md — cross-link added
  • packages/kilo-docs/pages/customize/index.md — overview entry added
  • packages/kilo-docs/lib/nav/customize.ts — nav entry added
  • packages/kilo-docs/pages/kiloclaw/development-tools/composio.md — URL updated

Fix these issues in Kilo Cloud

Previous review (commit d3172f3)

Status: No Issues Found | Recommendation: Merge

Previously Flagged (unchanged from prior review)
File Line Issue
packages/kilo-docs/pages/customize/agent-permissions.md 25 YAML vs JSON clarification for agent files vs kilo.jsonc
packages/kilo-docs/pages/customize/agent-permissions.md 36 Suggest adding Rule Precedence section to auto-approving-actions.md (addressed in this PR)
Files Reviewed (5 files)
  • packages/kilo-docs/pages/getting-started/settings/auto-approving-actions.md — example reordering to match last-match-wins precedence (fixes prior WARNING)
  • packages/kilo-docs/pages/customize/agent-permissions.md — unchanged from prior review
  • packages/kilo-docs/lib/nav/customize.ts — unchanged
  • packages/kilo-docs/pages/customize/custom-subagents.md — unchanged
  • packages/kilo-docs/pages/customize/index.md — unchanged
Incremental Review (3a55bce → d3172f3)

The incremental commit d3172f3 reorders all permission examples in auto-approving-actions.md to use last-match-wins ordering (broad fallbacks first, exceptions after), resolving the WARNING flagged in the previous review. All Shell Commands, File Reading, Blocking Dangerous Commands, Per-Agent, Markdown Agent Files, and Full Configuration examples are now consistent with the Rule Precedence section.

Previous review (commit 3a55bce)

Status: 1 Issue Found | Recommendation: Address before merge

Overview

Severity Count
CRITICAL 0
WARNING 1
SUGGESTION 0
Issue Details (click to expand)

WARNING

File Line Issue
packages/kilo-docs/pages/getting-started/settings/auto-approving-actions.md 130 New Rule Precedence section correctly documents last-match-wins, but pre-existing examples below (Shell Commands, File Reading, Blocking Dangerous Commands) use first-match-wins ordering. These examples need reordering to match the documented behavior.
Previously Flagged (unchanged from prior review)
File Line Issue
packages/kilo-docs/pages/customize/agent-permissions.md 25 YAML vs JSON clarification for agent files vs kilo.jsonc
packages/kilo-docs/pages/customize/agent-permissions.md 36 Suggest adding Rule Precedence section to auto-approving-actions.md (now addressed in this update)
Files Reviewed (2 files changed in this increment)
  • packages/kilo-docs/pages/customize/agent-permissions.md — intro rewrite (clean)
  • packages/kilo-docs/pages/getting-started/settings/auto-approving-actions.md — added Rule Precedence section, contradiction with existing examples

Previous review (commit 17fe1d6)

Status: No Issues Found | Recommendation: Merge

Notes

The page is well-structured with clear sections covering actions, precedence, patterns, file paths, shell commands, sensitive files, subagent delegation, and troubleshooting. Cross-links from Custom Subagents, the Customize index, and Auto-Approving Actions are correctly formatted.

Existing reviewer comments (intro clarity, adding Rule Precedence to auto-approving-actions) are reasonable suggestions but not blockers — the intro has already been revised and auto-approving-actions received a new Markdown Agent Files section.

All internal links (/docs/customize/custom-modes, /docs/customize/custom-subagents, /docs/getting-started/settings/auto-approving-actions, /docs/customize/context/kilocodeignore, /docs/automate/tools) resolve to existing pages.

This is a docs-only change — no changeset required.

Files Reviewed (5 files)
  • packages/kilo-docs/pages/customize/agent-permissions.md - New page
  • packages/kilo-docs/lib/nav/customize.ts - Navigation entry
  • packages/kilo-docs/pages/customize/custom-subagents.md - Cross-link update
  • packages/kilo-docs/pages/customize/index.md - Overview link
  • packages/kilo-docs/pages/getting-started/settings/auto-approving-actions.md - Markdown Agent Files section

Reviewed by deepseek-v4-pro-20260423 · 158,662 tokens

Review guidance: REVIEW.md from base branch main

@singhvishalkr

Copy link
Copy Markdown
Contributor Author

Current head now clarifies that the agent-permissions page is the YAML/frontmatter form, keeps the kilo.jsonc mapping explicit, and adds the same example under auto-approving actions. That should cover both review comments on the docs wording and placement.

@singhvishalkr

Copy link
Copy Markdown
Contributor Author

Updated in 3a55bce6b:

  • clarified that agent-permissions.md focuses on Markdown agent-file YAML frontmatter
  • added the same rule precedence explanation and examples to the kilo.jsonc auto-approve docs

Verification:

  • git diff --check

I could not run the docs package test/build locally because Bun is not available on this Windows environment.

@singhvishalkr
singhvishalkr force-pushed the docs/agent-permission-rules branch from d3172f3 to 6e99eb0 Compare June 16, 2026 17:21
@singhvishalkr

Copy link
Copy Markdown
Contributor Author

Rebased this on current main and updated the moved Composio toolkit catalog link that was failing link-checker. The docs build, markdown table check, forbidden-string check, link-checker, and typecheck jobs are passing on the latest head. Vercel still reports authorization required for the preview deployment.

Comment thread packages/kilo-docs/pages/customize/agent-permissions.md Outdated
@vercel

vercel Bot commented Jun 17, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
docs (docs-staging) Ready Ready Preview, Comment Jun 17, 2026 3:19am

Request Review

@lambertjosh lambertjosh left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks great, thanks for the changes! I fixed a minor conflict and we should be good.

@lambertjosh
lambertjosh enabled auto-merge June 17, 2026 03:18
@lambertjosh
lambertjosh merged commit 7849909 into Kilo-Org:main Jun 17, 2026
20 checks passed
t7tran pushed a commit to t7tran/kilocode that referenced this pull request Aug 14, 2026
…ssion-rules

docs(customize): clarify agent permission rules
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Agents permissions: order and rules application are not clear and poorly documented

2 participants