a8fc9c7715
* fix(shellcheck): declare and assign separately in router.sh (SC2155) * feat(plugin): enhance context management and skill invocation - Update .context-manifest.json to include profile and detailed source information. - Revise context-scout.md to clarify context root discovery and navigation. - Modify commands to replace deprecated skills with updated ones (brainstorming → approach, systematic-debugging → debugger). - Streamline install-context.md for clarity and remove interactive profile selection. - Improve oac-status.md to provide a more comprehensive status report. - Add OAC system paths to session-start.sh for better context management. - Remove obsolete skills and improve documentation for existing commands.
378 lines
7.6 KiB
Markdown
378 lines
7.6 KiB
Markdown
<!-- 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
|