#Agents & Permissions

OpenCode agents are not just different prompts—they are full configs with mode, model, and permission.

#Built-in Agents

#Build (Primary)

• Default main agent, full tools
• For: features, tests, multi-file edits

#Plan (Primary)

• Restricted agent: sensitive ops like edit, bash default to ask or deny
• For: design, review suggestions, refactor plans
• No surprise diffs—OpenCode’s “safe design mode”

#Explore (Subagent)

• Read-only, fast glob/grep/read
• For: “Where is this module?” “What API routes exist?”

#Scout (Subagent)

• Read-only, focused on external deps and upstream source
• For: third-party libs, cloned dependency cache

#General (Subagent)

• Full tools (except todo limits), can edit files
• For: parallel independent subtasks

#Switching and Invocation

Hidden agents (hidden: true) do not appear in @ menu but can still be invoked via task.

#JSON Agent Config

opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-6"
    },
    "plan": {
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-5",
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    },
    "code-reviewer": {
      "description": "Review code quality and security",
      "mode": "subagent",
      "permission": {
        "edit": "deny",
        "bash": {
          "*": "deny",
          "git diff*": "allow",
          "git log*": "allow"
        }
      }
    }
  }
}

#Markdown Agent Config

Paths:

• Global: ~/.config/opencode/agents/review.md
• Project: .opencode/agents/review.md

---
description: Security audit, read-only
mode: subagent
model: anthropic/claude-sonnet-4-6
temperature: 0.1
permission:
  edit: deny
  bash:
    "*": "ask"
    "grep *": allow
---

You are a security auditor focused on injection, auth, and dependency risks. Report only—do not edit files.

File review.md → agent name review.

#Interactive Create

opencode agent create

Wizard asks location, description, permission checkboxes, and writes a Markdown agent file.

opencode agent list

#Permission Advanced

#Global default + agent override

{
  "permission": {
    "edit": "ask"
  },
  "agent": {
    "build": {
      "permission": {
        "edit": "allow"
      }
    }
  }
}

#task permission (who can call which subagent)

"permission": {
  "task": {
    "*": "deny",
    "explore": "allow",
    "code-reviewer": "ask"
  }
}

With deny, that subagent is removed from task tool descriptions; users can still @ invoke manually.

#steps limit (cost control)

"agent": {
  "quick-fix": {
    "steps": 5
  }
}

At the step cap, the agent must summarize instead of calling more tools.

#Typical Combinations

#Next Steps

• MCP & LSP
• Config & CLI Reference
• Practical Examples