Should we actually implement the new granular permissions in .md agent files?

Question

I see that the tools configuration has been deprecated in favor of the new permission system in OpenCode. The documentation provides clear examples for JSON configurations, such as:

{
  "permission": {
    "bash": {
      "npm *": "allow",
      "*": "ask"
    }
  }
}

Since it appears that the legacy tools configuration is still being picked up in .md files, I am unsure if this is intended to be stable behavior or just a temporary side effect of the migration logic.

Does the frontmatter in .md agents now support the same object-based permission syntax?
Could you provide an example of how to define these granular permissions (e.g., specific bash command patterns) directly within the Markdown file's metadata?
Is it safe to continue using the old tools field in .md files, or should we migrate them to the new format immediately to avoid breakage?

This is crucial for keeping our agents and subagents functional and secure without relying on manual session switches.

yes
sure I think there is already one in docs tho
I'd migrate them when if u can but it is safe for now

@rekram1-node

hi @rekram1-node -the new release's (v1.1.1) permissions update seems to have broken how granular permissions are handled.

if you copy the review subagent markdown example from https://opencode.ai/docs/agents/#permissions:

---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash:
    "git diff": allow
    "git log*": allow
    "*": ask
  webfetch: deny
---

Only analyze code and suggest changes.

and then ask that subagent to run git log, OpenCode still requests permission despite the config explicitly allowing the command.

similarly, if you change the * permission to "*": deny, the review subagent is denied from all bash commands (including the explicitly allowed ones).

I concur with shanebishop: I use granular frontmatter permissions in my agent md files and since the upgrade to opencode 1.1.1 and 1.1.2 opencode started asking me permission for things that were explicitly allowed in frontmatter, e.g. ls, grep, git log, etc.

EDIT: or can it be that piped commands now belong to the same "atomic" granular permission? As they are all mentioned when I need to permit certain commands that were piped thus part of the same "total command", e.g. npm test ... | tail -n 20 asks me for a combined permission for npm test and tail in a single permission bundle if you will.

@shanebishop1

@shanebishop1 coz in the new permission system, order matters. since you have that "*" at the very end it overrides the above statements. looking at the commit history that seems intended

@thdxr

Before: More specific patterns took priority over wildcards (specificity-based matching).

After: Rules are evaluated in declaration order using findLast(), with the last matching rule winning.

Example of breaking change:

# In the OLD system, this would DENY rm commands (specific pattern wins)
# In the NEW system, this ALLOWS everything including rm (last match wins)
permission:
  bash:
    "rm*": deny
    "*": allow

Correct order in new system:

# Catch-all FIRST, specific patterns LAST
permission:
  bash:
    "*": allow
    "rm*": deny

@thdxr can you confirm if this indeed intentional? This is a significant behavioral change that could silently break existing configurations.

@malhashemi

@malhashemi it is intentional

Note that in all our docs and examples I think we've always done the ordered version, I think ordered is the most intuitive and natural

@rekram1-node

@rekram1-node I agree I always had them ordered, just that I can imagine so many configs are broken now, need to highlight this strong enough.

/oc use docs agent to update permissions.mdx to highlight that ORDER MATTERS, use the context of this issue to help you properly document this

Created PR #7033

opencode session | github run

@rekram1-node

@rekram1-node I think the disconnect here comes from there being a "Permissions" subsection in the Agents section of the docs. This section has not been updated to align with this order priority.

If you look here https://opencode.ai/docs/agents/#permissions, you'll see the example that I previously included, which does not follow the last-match-priority rule. At least, it doesn't read that way because the first two matches are basically useless as it stands right now (the * takes priority).

#7041 should clarify

Navigation Menu

Repository navigation

Should we actually implement the new granular permissions in .md agent files? #6856

Question

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Should we actually implement the new granular permissions in .md agent files? #6856

Description

Question

Activity

rekram1-node commented on Jan 4, 2026

shanebishop1 commented on Jan 5, 2026

doodhout commented on Jan 5, 2026

malhashemi commented on Jan 6, 2026

malhashemi commented on Jan 6, 2026

rekram1-node commented on Jan 6, 2026

rekram1-node commented on Jan 6, 2026

malhashemi commented on Jan 6, 2026

rekram1-node commented on Jan 6, 2026

opencode-agent commented on Jan 6, 2026

shanebishop1 commented on Jan 6, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions