OpenWriterControle/.opencode/context/openagents-repo/standards/permission-patterns.md

Standard: Permission Patterns for OpenCode v1.1.1+

Purpose: Comprehensive permission configuration patterns for different agent types
Priority: CRITICAL - Load this before configuring agent permissions

---

Core Principle

OpenCode v1.1.1+ uses permission: (singular) with granular control over tool access. Rules follow last-matching-wins evaluation order.

Why: Granular permissions prevent unintended actions while allowing necessary operations.

---

Permission Evaluation Order

Last matching rule wins - Common pattern:

1. Catch-all "*" first (default behavior)
2. Specific overrides after (take precedence)

Example:

permission:
  bash:
    "*": "deny"              # Catch-all: deny all bash
    "git status*": "allow"   # Override: allow git status
    "git diff*": "allow"     # Override: allow git diff

---

Valid Permission Keys

Key	Description	Granular?	Default
read	File reading	Yes (path globs)	"allow"
edit	File modifications	Yes (path globs)	"allow"
glob	File globbing/searches	Yes	"allow"
grep	Content/regex search	Yes	"allow"
list	Directory listing	Yes	"allow"
bash	Shell commands	Yes (command globs)	"allow"
task	Subagent launches	Yes (subagent type)	"allow"
skill	Skill loading	Yes	"allow"
lsp	LSP queries	No	"allow"
todoread	Todo list read	No	"allow"
todowrite	Todo list update	No	"allow"
webfetch	URL fetching	Yes	"allow"
websearch	Web search	Yes	"allow"
codesearch	Code search	Yes	"allow"
external_directory	Out-of-project paths	Yes	"ask"
doom_loop	Repeated identical calls	Yes	"ask"

---

Valid Actions

• "allow" - Executes without approval
• "ask" - Prompts user (options: once, always, reject)
• "deny" - Blocks immediately

---

Agent Type Patterns

Read-Only Agents (Reviewers, Analyzers)

Use case: Code review, analysis, security audits

permission:
  bash:
    "*": "deny"
  edit:
    "**/*": "deny"
  write:
    "**/*": "deny"
  task:
    contextscout: "allow"
    "*": "deny"

Examples: CodeReviewer, SecurityAuditor

---

Write-Enabled Agents (Coders, Testers)

Use case: Code implementation, test authoring

permission:
  bash:
    "rm -rf *": "ask"
    "sudo *": "deny"
    "chmod *": "ask"
    "curl *": "ask"
    "wget *": "ask"
    "docker *": "ask"
    "kubectl *": "ask"
    # Test-specific commands (for testers)
    "npx vitest *": "allow"
    "npx jest *": "allow"
    "pytest *": "allow"
    "npm test *": "allow"
    "go test *": "allow"
    "cargo test *": "allow"
    "*": "deny"
  edit:
    "**/*.env*": "deny"
    "**/*.key": "deny"
    "**/*.secret": "deny"
    "node_modules/**": "deny"
    "**/__pycache__/**": "deny"
    "**/*.pyc": "deny"
    ".git/**": "deny"
  task:
    contextscout: "allow"
    "*": "deny"

Examples: CoderAgent, TestEngineer, BuildAgent

---

Orchestrators (Task Managers, Primary Agents)

Use case: Workflow orchestration, task delegation

permission:
  bash:
    "rm -rf *": "ask"
    "sudo *": "deny"
    "chmod *": "ask"
    "*": "ask"  # More permissive for orchestration
  edit:
    "**/*.env*": "deny"
    "**/*.key": "deny"
    "**/*.secret": "deny"
    "node_modules/**": "deny"
    ".git/**": "deny"
  task:
    "*": "allow"  # Can delegate to any subagent

Examples: OpenCoder, OpenAgent, TaskManager

---

Restricted Bash Agents (Specific Commands Only)

Use case: Agents that need only specific bash commands

permission:
  bash:
    "git status*": "allow"
    "git diff*": "allow"
    "git log*": "allow"
    "ls *": "allow"
    "cat *": "allow"
    "*": "deny"
  edit:
    "**/*.env*": "deny"
  task:
    contextscout: "allow"
    "*": "deny"

Examples: ExternalScout, ContextScout

---

Security Patterns

Always Deny Sensitive Files

permission:
  edit:
    "**/*.env*": "deny"
    "**/*.key": "deny"
    "**/*.secret": "deny"
    "**/*.pem": "deny"
    "**/*.crt": "deny"
    "**/credentials*": "deny"

Always Deny Dangerous Commands

permission:
  bash:
    "sudo *": "deny"
    "rm -rf /*": "deny"
    "chmod 777 *": "deny"
    "curl * | bash": "deny"
    "wget * | sh": "deny"

Always Ask for Destructive Operations

permission:
  bash:
    "rm -rf *": "ask"
    "git push --force*": "ask"
    "docker system prune*": "ask"
    "npm publish*": "ask"

---

Task Permission Patterns

Allow Specific Subagents Only

permission:
  task:
    contextscout: "allow"
    externalscout: "allow"
    "*": "deny"

Allow All Except Specific

permission:
  task:
    "*": "allow"
    "dangerous-agent": "deny"

Ask for Orchestration Agents

permission:
  task:
    contextscout: "allow"      # Always allow context discovery
    "coder-agent": "ask"        # Ask before code generation
    "build-agent": "ask"        # Ask before builds
    "*": "deny"

---

Complete Examples

Example 1: Code Reviewer (Read-Only)

---
name: CodeReviewer
description: Code review, security, and quality assurance agent
mode: subagent
temperature: 0.1
tools:
  read: true
  grep: true
  glob: true
  bash: false
  edit: false
  write: false
  task: true
permission:
  bash:
    "*": "deny"
  edit:
    "**/*": "deny"
  write:
    "**/*": "deny"
  task:
    contextscout: "allow"
    "*": "deny"
---

Example 2: Test Engineer (Write-Enabled)

---
name: TestEngineer
description: Test authoring and TDD agent
mode: subagent
temperature: 0.1
tools:
  read: true
  grep: true
  glob: true
  edit: true
  write: true
  bash: true
  task: true
permission:
  bash:
    "npx vitest *": "allow"
    "npx jest *": "allow"
    "pytest *": "allow"
    "npm test *": "allow"
    "go test *": "allow"
    "cargo test *": "allow"
    "rm -rf *": "ask"
    "sudo *": "deny"
    "*": "deny"
  edit:
    "**/*.env*": "deny"
    "**/*.key": "deny"
    "**/*.secret": "deny"
  task:
    contextscout: "allow"
    "*": "deny"
---

Example 3: Primary Orchestrator

---
name: OpenCoder
description: Orchestration agent for complex coding
mode: primary
temperature: 0.1
tools:
  task: true
  read: true
  edit: true
  write: true
  grep: true
  glob: true
  bash: true
permission:
  bash:
    "rm -rf *": "ask"
    "sudo *": "deny"
    "chmod *": "ask"
    "curl *": "ask"
    "wget *": "ask"
    "docker *": "ask"
    "kubectl *": "ask"
  edit:
    "**/*.env*": "deny"
    "**/*.key": "deny"
    "**/*.secret": "deny"
    "node_modules/**": "deny"
    ".git/**": "deny"
  task:
    "*": "allow"
---

---

Validation Checklist

• Using permission: (singular, not permissions:)
• Catch-all rules ("*") come FIRST
• Specific overrides come AFTER catch-all
• Sensitive files denied (**/*.env*, **/*.key, **/*.secret)
• Dangerous commands denied (sudo *, rm -rf /*)
• Destructive operations ask (rm -rf *, git push --force*)
• Task permissions appropriate for agent type
• Valid actions only ("allow", "ask", "deny")

---

Related

• Agent Frontmatter: standards/agent-frontmatter.md
• Subagent Structure: standards/subagent-structure.md
• Security Patterns: ../../core/standards/security-patterns.md
• OpenCode Docs: https://opencode.ai/docs/permissions/

---

Last Updated: 2026-02-01 | Version: 1.0.0