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

[canomogollon]

Following up on this — we implemented a production-safe permission pattern that might be relevant to the skill permission validation system you're designing.

Deny-by-Default with Explicit Allows

Instead of permissive defaults, we use operation-level deny-by-default with explicit allowlists:

{
  "agents": {
    "ContextScout": {
      // Read-only discovery agent
      "permissions": {
        "*": "deny",
        "read": "allow",
        "glob": "allow",
        "grep": "allow",
        "skill": "allow",
        "webfetch": "allow"
      }
    },
    "CoderAgent": {
      // Write-capable coding agent
      "permissions": {
        "*": "deny",
        "read": "allow",
        "glob": "allow",
        "grep": "allow",
        "write": "allow",
        "edit": "allow",
        "bash": "allow"
      }
    },
    "CodeReviewer": {
      // Read-only review agent
      "permissions": {
        "*": "deny",
        "read": "allow",
        "glob": "allow",
        "grep": "allow",
        "skill": "allow"
      }
    }
  }
}

Why This Works

• Zero tool-hallucination: If a model tries to call an unavailable tool, it's denied by default rather than prompting the user.
• Security-by-construction: Read-only agents literally cannot write files, even if the model hallucinates.
• Clear intent: The permission manifest tells you exactly what each agent can do at a glance.

Context Discovery Pattern

For runtime context discovery, we use a local-first approach:

1. ContextScout scans .opencode/context/core/navigation.md before any operation
2. All context files are MVI-compliant (<200 lines, function-based structure)
3. Context is bundled per-delegation: .tmp/sessions/{id}/context.md with task + constraints

The combination of deny-by-default + MVI context files means agents operate within well-defined boundaries without needing runtime policy evaluation for every tool call.

Would love to see this formalized as a plugin architecture. Happy to share our full permission matrix if useful. ⚡