anomalyco/opencode
1
0
Fork 0
mirror of https://github.com/anomalyco/opencode.git synced 2026-07-23 02:36:57 -04:00
Code Issues 5.9k Packages Projects Releases 19 Wiki Activity

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

New Issue
Closed
opened 2026-02-16 18:05:05 -05:00 by yindo · 0 comments
yindo commented 2026-02-16 18:05:05 -05:00
Owner
Copy Link
Copy Source

Originally created by @alanpog on GitHub (Jan 18, 2026).

Originally assigned to: @jayair on GitHub.

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"
Originally created by @alanpog on GitHub (Jan 18, 2026). Originally assigned to: @jayair on GitHub. ## Description The [Agents documentation](https://opencode.ai/docs/agents/) has two issues that could confuse users. ### Issue 1: "Primary agents can access all configured tools" The [Primary agents section](https://opencode.ai/docs/agents/#primary-agents) 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](https://opencode.ai/docs/agents/#built-in) 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"
yindo added the docs label 2026-02-16 18:05:05 -05:00
yindo closed this issue 2026-02-16 18:05:05 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
acp
bad
bug
discussion
docs
documentation
enhancement
extension
good first issue
growth
help-wanted
mcp
model-problem
needs:compliance
nix
opentui
perf
pull-request
Mirrored from GitHub Pull Request
 tui
web
windows
zen
No Label docs
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: anomalyco/opencode#6729
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?