Fixing OpenCode Planner Agent Executing Code via Subagents

The Root Cause: Conflated Concerns

The core issue in OpenCode was that agent configuration conflated two very different problems:

1. Human Visibility:Whether a subagent appears in the UI menus/autocomplete for the user.
2. LLM Invocation Control:Which subagents a primary agent is allowed to spawn.

When you set edit: deny and bash: deny on a planner agent, the LLM realizes it can't do the work directly. Because there was no strict control over the task (subagent spawning) tool, the LLM simply delegated the execution to a default subagent that did have those permissions. It found a loophole.

The Solution: Separating UX and LLM Control

Thanks to the design proposed in the GitHub PR, we can now cleanly separate these concerns using three specific configuration properties: visible, permission.task, and tools.task.

1. LLM Invocation Control: permission.task

To stop your planner agent from spawning execution subagents, you must explicitly control its task permissions. This uses the same pattern as permission.bash.

You can use "allow", "ask", or "deny". Crucially, denying a task removes the subagent from the Task tool description in the system prompt, preventing the LLM from hallucinating or attempting to use it.

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "plan": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny"
        }
      }
    },
    "orchestrator": {
      "description": "Main orchestration agent",
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-coder": "allow",
          "orchestrator-quality-gate": "ask"
        }
      }
    }
  }
}

Note: Rules are evaluated sequentially. "*": "deny" should be placed first to act as a default, followed by specific allowances. Wildcards like "orchestrator-*": "allow" are also supported.

2. Human Visibility: visible property

If you have internal subagents (like orchestrator-coder) that you don't want cluttering your Tab rotation or agent menu, you can hide them from the human UI without affecting the LLM's ability to spawn them.

Add a visible property (default is true) to the subagent's configuration:

{
  "agent": {
    "orchestrator-coder": {
      "description": "Internal coding subagent for orchestration loops",
      "mode": "subagent",
      "visible": false
    }
  }
}

Rules for visible:

• visible: false hides the subagent from the agent menu.
• It does NOT apply to mode: primary or mode: all agents (these are always visible).
• It does NOT affect whether the LLM can invoke the subagent (that is controlled by permission.task).

3. Disabling the Task Tool Entirely: tools.task

If you want a primary agent to be completely incapable of spawning any subagents whatsoever (which is exactly what I needed for my strict Planner Agent), you can disable the Task tool entirely.

{
  "agent": {
    "simple-build": {
      "mode": "primary",
      "tools": {
        "task": false
      }
    }
  }
}

Complete Configuration Example

Here is a complete config.json showing all these features working together to create a robust, safe agent ecosystem:

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",
          "code-reviewer": "allow",
          "explore": "allow",
          "general": "allow"
        }
      }
    },
    "orchestrator": {
      "description": "Automated orchestration agent",
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-coder": "allow",
          "orchestrator-planner": "allow",
          "orchestrator-quality-gate": "ask"
        }
      }
    },
    "orchestrator-coder": {
      "description": "Internal: Handles coding tasks for orchestrator",
      "mode": "subagent",
      "visible": false
    },
    "orchestrator-planner": {
      "description": "Internal: Handles planning for orchestrator",
      "mode": "subagent",
      "visible": false
    },
    "orchestrator-quality-gate": {
      "description": "Internal: Quality verification",
      "mode": "subagent",
      "visible": false
    },
    "code-reviewer": {
      "description": "Reviews code for best practices and issues",
      "mode": "subagent",
      "visible": true,
      "tools": {
        "write": false,
        "edit": false,
        "task": false
      }
    }
  }
}

How this config behaves:

• The Build agent can invoke code-reviewer, explore, and general, but NOT any orchestrator-* subagents.
• The Orchestrator agent can only invoke its own internal subagents, with orchestrator-quality-gate requiring user approval ("ask") before spawning.
• The human user sees only the build, orchestrator, and code-reviewer agents in the UI menu. The internal orchestrator subagents are hidden.
• The code-reviewer cannot write, edit, or spawn its own subagents (preventing infinite loops).

Summary of Config Properties

To wrap up, here is a quick cheat sheet for your OpenCode agent configurations:

This new design cleanly separates human UX from LLM behavior, follows standard config merging patterns, and finally solves the planner agent execution bypass.