feat(plugin): enhance context management and skill invocation (#239 )

* 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.

2026-02-23 12:12:29 +00:00

7.6 KiB

Raw Blame History

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:

Catch-all "*" first (default behavior)
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")

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

7.6 KiB Raw Blame History