Implement runtime context discovery and skill permission validation

[darrenhinde]

Overview

Build a runtime context discovery mechanism and skill permission validation system to improve security, clarity, and developer experience when working with context files and agent skills.

Goals

• Build runtime context file discovery mechanism
• Add automatic context loading based on task type
• Implement skill permission validation system
• Create context lifecycle management (discovery → loading → injection)
• Add CLI commands for permission validation
• Document context system architecture
• Build debugging tools for context issues

Key Features

Runtime Discovery

• Automatic context file detection in .opencode/context/
• Task-type based context loading
• Priority-based context selection
• Context dependency resolution

Permission System

• Skill permission validation in agent frontmatter
• opencode.json permission configuration
• Tool access restrictions per skill
• Permission inheritance and overrides

Context Lifecycle

1. Discovery - Find relevant context files
2. Loading - Read and parse context
3. Validation - Check permissions and dependencies
4. Injection - Add to agent prompt
5. Cleanup - Remove when no longer needed

CLI Commands

• /validate-permissions - Check agent permissions
• /discover-context - Show available context files
• /context-status - View loaded context
• /reload-context - Refresh context files

Debugging Tools

• Context loading trace logs
• Permission violation warnings
• Missing context detection
• Circular dependency detection

Related Issues

• Clarify .opencode/context/ runtime discovery and per‑agent skill permission handling in /build-context-system #120 (Context runtime discovery and skill permissions)

Success Criteria

• Runtime discovery implemented
• Permission validation working
• Context lifecycle management complete
• CLI commands functional
• Debugging tools available
• Architecture documented
• Examples and guides provided

[Protocol-zero-0]

Proposal: Granular Capability Scopes for Permission Validation

When implementing skill permission validation (#140), consider moving beyond binary flags (allow/deny) to scoped capabilities immediately.

For example, in opencode.json:

"permissions": {
  "fs:read": ["./logs/*.log", "./config/*.json"],
  "net:fetch": ["https://api.github.com/*"]
}

This prevents the classic 'check-box security' where an agent gets full filesystem access just because it needs to read one config file. It aligns with the principle of least privilege crucial for sovereign agents.

[darrenhinde]

This is a good idea appreciate the thought on this.
Will have to go into a plugin format due to limitations.

[Protocol-zero-0]

Understood. A plugin architecture makes sense for extensibility here. Happy to review the interface design when you get to it. ⚡