cclohmar/OpenWriterControle
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
OpenWriterControle/.opencode/context/openagents-repo/standards/permission-patterns.md
Darren Hinde b41641cfb2
fix: correct YAML errors and restore missing permissions in agent configs (#167) 
* fix: migrate all agents to OpenCode v1.1.1+ permission (singular) key

Resolves #164

## Changes

### Agent Files (16 files)
- Migrated all agent frontmatter from deprecated `permissions:` (plural) to `permission:` (singular)
- Updated: core agents (OpenCoder, OpenAgent, RepoManager)
- Updated: code subagents (TestEngineer, CoderAgent, BuildAgent, CodeReviewer)
- Updated: core subagents (TaskManager, DocWriter, ExternalScout, ContextScout, ContextManager, Context Retriever)
- Updated: development subagents (DevOpsSpecialist, FrontendSpecialist)
- Updated: system-builder subagents (ContextOrganizer, WorkflowDesigner)

### Context Documentation (3 files)

#### Updated: agent-frontmatter.md
- Fixed field name from `permissions:` to `permission:`
- Updated all examples to use correct singular form
- Corrected "Wrong Field Names" section to show `permissions:` as deprecated
- Updated validation checklist and valid keys list

#### Updated: agent-metadata.md
- Added clarification that `permission` replaces deprecated `permissions`
- Added comprehensive migration guide with before/after examples
- Added validation steps for migration

#### New: permission-patterns.md
- Comprehensive 400+ line permission patterns reference
- Permission evaluation order (last-matching-wins)
- Complete table of valid permission keys
- Agent type patterns (read-only, write-enabled, orchestrators)
- Security patterns (sensitive files, dangerous commands)
- Task permission patterns
- Complete working examples for each agent type
- Validation checklist

## Verification

- ✅ 0 agents using deprecated `permissions:` (plural)
- ✅ 16 agents using correct `permission:` (singular)
- ✅ All permission patterns follow last-matching-wins order
- ✅ Security denials applied consistently
- ✅ Context documentation updated and accurate

## Migration Details

Based on official OpenCode documentation (https://opencode.ai/docs/agents/):
- OpenCode v1.1.1+ uses `permission:` (singular)
- Deprecated: `permissions:` (plural)
- Granular control with last-matching-wins evaluation
- Valid actions: "allow", "ask", "deny"

All agents now comply with OpenCode v1.1.1+ standards.

* fix: correct YAML errors and restore missing permissions in agent configs

- Fix repo-manager.md duplicate permission section
- Fix externalscout.md YAML indentation error
- Remove old tools: section from devops-specialist.md
- Restore context file permissions in context-manager.md
- Restore test command permissions in tester.md
- Clean up formatting in coder-agent.md

All 20 agent files now have valid YAML frontmatter with proper permission blocks.
2026-02-02 15:09:46 +00:00

378 lines
7.6 KiB
Markdown
Raw Blame History

<!-- 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
Reference in a new issue View git blame Copy permalink