|
|
@@ -0,0 +1,378 @@
|
|
|
+<!-- Context: openagents-repo/standards/permission-patterns | Priority: critical | Version: 1.0 | Updated: 2026-02-01 -->
|
|
|
+# 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:
|
|
|
+```yaml
|
|
|
+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
|
|
|
+
|
|
|
+```yaml
|
|
|
+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
|
|
|
+
|
|
|
+```yaml
|
|
|
+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
|
|
|
+
|
|
|
+```yaml
|
|
|
+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
|
|
|
+
|
|
|
+```yaml
|
|
|
+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
|
|
|
+
|
|
|
+```yaml
|
|
|
+permission:
|
|
|
+ edit:
|
|
|
+ "**/*.env*": "deny"
|
|
|
+ "**/*.key": "deny"
|
|
|
+ "**/*.secret": "deny"
|
|
|
+ "**/*.pem": "deny"
|
|
|
+ "**/*.crt": "deny"
|
|
|
+ "**/credentials*": "deny"
|
|
|
+```
|
|
|
+
|
|
|
+### Always Deny Dangerous Commands
|
|
|
+
|
|
|
+```yaml
|
|
|
+permission:
|
|
|
+ bash:
|
|
|
+ "sudo *": "deny"
|
|
|
+ "rm -rf /*": "deny"
|
|
|
+ "chmod 777 *": "deny"
|
|
|
+ "curl * | bash": "deny"
|
|
|
+ "wget * | sh": "deny"
|
|
|
+```
|
|
|
+
|
|
|
+### Always Ask for Destructive Operations
|
|
|
+
|
|
|
+```yaml
|
|
|
+permission:
|
|
|
+ bash:
|
|
|
+ "rm -rf *": "ask"
|
|
|
+ "git push --force*": "ask"
|
|
|
+ "docker system prune*": "ask"
|
|
|
+ "npm publish*": "ask"
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## Task Permission Patterns
|
|
|
+
|
|
|
+### Allow Specific Subagents Only
|
|
|
+
|
|
|
+```yaml
|
|
|
+permission:
|
|
|
+ task:
|
|
|
+ contextscout: "allow"
|
|
|
+ externalscout: "allow"
|
|
|
+ "*": "deny"
|
|
|
+```
|
|
|
+
|
|
|
+### Allow All Except Specific
|
|
|
+
|
|
|
+```yaml
|
|
|
+permission:
|
|
|
+ task:
|
|
|
+ "*": "allow"
|
|
|
+ "dangerous-agent": "deny"
|
|
|
+```
|
|
|
+
|
|
|
+### Ask for Orchestration Agents
|
|
|
+
|
|
|
+```yaml
|
|
|
+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)
|
|
|
+
|
|
|
+```yaml
|
|
|
+---
|
|
|
+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)
|
|
|
+
|
|
|
+```yaml
|
|
|
+---
|
|
|
+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
|
|
|
+
|
|
|
+```yaml
|
|
|
+---
|
|
|
+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
|
Darren Hinde