docs: Agents page has misleading/incomplete information about tool access

[alanpog]

Description

The Agents documentation has two issues that could confuse users.

Issue 1: "Primary agents can access all configured tools"

The Primary agents section states:

"These agents handle your main conversation and can access all configured tools."

This is incorrect. Looking at the code (packages/opencode/src/agent/agent.ts), tool access is controlled by the permission system, not agent mode. Any agent can have tools restricted or removed via permissions.

The built-in plan agent (a primary agent) demonstrates this — it has edit: { "*": "deny", ... } to restrict file modifications. The docs even show examples of restricting primary agents later on the same page (e.g., tools: { "write": false }), which contradicts this statement.

Issue 2: Explore vs General distinction is unclear

The Built-in section describes:

• General: "researching complex questions, searching for code, and executing multi-step tasks"
• Explore: "quickly find files by patterns, search code for keywords, or answer questions about the codebase"

These sound nearly identical, but looking at the code there's a critical difference:

• explore is read-only — uses "*": "deny" then allows only: grep, glob, list, bash, read, webfetch, websearch, codesearch
• general has full tool access — only denies todoread/todowrite, can edit/write files

Users choosing between these agents would benefit from knowing that explore cannot modify files while general can.

Suggested fix

1. Rephrase to something like: "These agents handle your main conversation. Tool access is controlled via permissions — for example, Build has access to all tools while Plan is restricted."

2. Clarify the explore/general distinction:

   • General: "...can execute changes including file edits"
   • Explore: "...read-only agent that cannot modify files"