[background-agents] explore agent incorrectly detected as write-capable

[indigoviolet]

Plugin

kdco/background-agents

Summary

The delegate tool incorrectly rejects the explore agent as "write-capable" when it should be a valid read-only delegation target. The error message is also self-contradictory.

Steps to Reproduce

1. Configure OpenCode with the default explore subagent
2. Attempt to delegate to the explore agent:

   delegate("Search for authentication code", "explore")
   

Expected Behavior

Delegation should succeed since explore is a read-only agent designed for codebase exploration.

Actual Behavior

Delegation fails with:

❌ Delegation failed:

Agent "explore" is write-capable and requires the native `task` tool for proper undo/branching support.

Use `task` instead of `delegate` for write-capable agents.

Read-only agents (researcher, explore) use `delegate`.   <-- contradicts the error!
Write-capable agents (coder, scribe) use `task`.

Root Cause Analysis

The issue is in parseAgentWriteCapability() in background-agents.ts:

async function parseAgentWriteCapability(...): Promise<{ isReadOnly: boolean }> {
  const permission = configData?.agent?.[agentName]?.permission ?? {}

  const editDenied = isPermissionDenied(permission.edit)
  const writeDenied = isPermissionDenied(permission.write)
  const bashDenied = isPermissionDenied(permission.bash)

  return { isReadOnly: editDenied && writeDenied && bashDenied }
}

Problem 1: Permission schema mismatch

The function expects permissions in this format:

{ "edit": "deny", "write": "deny", "bash": "deny" }

But OpenCode's actual permission schema (from opencode agent list) is an array of rules:

[
  { "permission": "*", "action": "deny", "pattern": "*" },
  { "permission": "grep", "action": "allow", "pattern": "*" },
  { "permission": "bash", "action": "allow", "pattern": "*" },
  ...
]

Problem 2: bash: allow ≠ write-capable

The explore agent has bash: allow because it needs to run read-only commands like rg, fd, git log, etc. However, the plugin's heuristic treats any bash access as "write-capable", which is incorrect.

The actual explore agent permissions show:

• "*": "deny" (deny all by default)
• Explicitly allows: grep, glob, list, bash, webfetch, websearch, codesearch, read
• Does NOT allow: edit, write

Suggested Fix

Option A: Check for explicit edit and write permissions only, ignoring bash:

return { isReadOnly: editDenied && writeDenied }

Option B: Parse the actual OpenCode permission array format and check if edit/write tools are allowed:

const rules = permissionArray ?? []
const hasWriteAccess = rules.some(r => 
  (r.permission === 'edit' || r.permission === 'write') && 
  r.action === 'allow'
)
return { isReadOnly: !hasWriteAccess }

Option C: Use an allowlist of known read-only agents:

const READ_ONLY_AGENTS = ['explore', 'researcher']
return { isReadOnly: READ_ONLY_AGENTS.includes(agentName) }

Environment

• OpenCode version: latest
• background-agents plugin: latest from registry
• OS: macOS

[kdcokenny]

Are you sure you don't have global perms overriding local ones? This works as expected for me in a clean config.

[kdcokenny]

Here are working perms for the explorer:

      "permission": {
        "edit": "deny",
        "write": "deny",
        "plan_read": "deny",
        "todoread": "deny",
        "bash": {
          "*": "deny",
          "ls *": "allow",
          "tree *": "allow",
          "pwd": "allow",
          "cat *": "allow",
          "head *": "allow",
          "tail *": "allow",
          "wc *": "allow",
          "file *": "allow",
          "stat *": "allow",
          "grep *": "allow",
          "rg *": "allow",
          "find *": "allow",
          "git status*": "allow",
          "git log*": "allow",
          "git diff*": "allow",
          "git show*": "allow",
          "git blame*": "allow",
          "git branch*": "allow",
          "git ls-files*": "allow",
          "uname*": "allow",
          "hostname": "allow",
          "whoami": "allow",
          "which *": "allow",
          "realpath *": "allow"
        }
      }

[indigoviolet]

I can look more, but @explore was working for me in Plan mode until I installed this plugin

[indigoviolet]

Do you disagree with the root cause analysis above?

[kdcokenny]

I mean i'd have to look into it further but their docs still reference edit, write, and bash: https://opencode.ai/docs/agents/#permissions

[kdcokenny]

either way this shouldn't break the native explore agent, it just makes it so that you have to call it with the sync task rather than async delegate.