subagents: explore agent denied free tier can only be used from within OpenCode while running inside the CLI — general works with identical models

Author: OpenCode (bug report generated by the OpenCode CLI agent while reproducing the failure).

Summary

While running as a session inside the OpenCode CLI, I reproduced a consistent defect in the
built-in explore subagent: every invocation fails with
Error from provider (Console): OpenCode's free tier can only be used from within OpenCode
even though this session is running inside the OpenCode CLI itself, my main agent uses
OpenCode Zen free models fine, and the built-in general subagent succeeds with the identical
model IDs. The free-tier entitlement check only misclassifies the explore request path — a
routing defect in the built-in agent, not a policy the user tripped.

Environment

opencode version: v2.0.7
OS: Microsoft Windows 10.0.26100.9457 (build 26100), x64 (AMD64)
Terminal: xterm-256color; TERM_PROGRAM and COLORTERM unset
Shell: C:\Windows\system32\cmd.exe (ComSpec)
Install/channel: latest via npm @opencode-ai/cli (wrapper opencode.ps1 → binary opencode2.exe, 148 MB); Node v22.18.0, npm 11.19.1
Active plugins: none found in config (checked opencode.json, ~/.config/opencode/opencode.json — only cli.json + service.json exist under ~/.config/opencode/, no agent overrides)

Reproduction

Started a session inside the OpenCode CLI (main agent = opencode/big-pickle, runs fine).
Invoked the subagent tool with agent = "explore" and a minimal prompt:
```
{ "agent": "explore", "prompt": "quick test" }
```

Observed the failure — including when a model was pinned:

{ "agent": "explore", "model": "opencode/muse-spark-1.3-contributor-free", "prompt": "quick test" }

Invoked the same subagent with agent = "general" and the same model ID — it succeeded.

Models tried with `explore` (all FAIL with identical error)

All OpenCode Zen models:

default (no model)
opencode/big-pickle
opencode/muse-spark-1.3-contributor-free
opencode/muse-spark-1.2-contributor-free
opencode/ling-3.0-flash-fin-free
opencode/mimo-v2.5-free
opencode/nemotron-3-ultra-free
opencode/nemotron-3.5-lightning-free

Models tried with `general` (all SUCCEED)

All OpenCode Zen models:

opencode/ling-3.0-flash-fin-free
opencode/muse-spark-1.3-contributor-free
opencode/mimo-v2.5-free

Note: google/gemini-3.5-flash-lite was tested separately and works — but it is a
Google API model, not an OpenCode Zen free model. It is not part of the OpenCode
free-tier pool, so it was excluded from this.

Expected Behavior

Within the OpenCode CLI, the free-tier entitlement gate should pass for every built-in agent
using the same models — including explore. At minimum, explore should behave identically to
general for identical model IDs.

Actual Behavior

Every explore invocation returns the same hard error before any work happens:

Subagent failed (sessionID: ses_...): Error from provider (Console): OpenCode's free tier can only be used from within OpenCode

The main session (OpenCode Zen, opencode/big-pickle) and general subagents with the same
models work normally. The gate's "within OpenCode" check is therefore passing for some request
paths and failing for the explore one — inside the very same CLI session.

Additional Context

Frequency: 8/8 explore invocations failed; 3/3 general invocations succeeded. Consistent.
Recent changes: unknown; no config/plugin changes made before testing.
Workarounds: use general agent (with any OpenCode Zen model) instead of explore.
This is a clean substitute for the exploration workload in this session.

I reproduced this with the official v2.0.7 macOS binary and an isolated config, so it is not Windows-specific.

general + opencode/mimo-v2.5-free succeeds.
explore + the same model fails with the reported 403.
Replacing explore's system prompt with the normal OpenCode harness identity still fails.
Keeping the built-in explore agent but allowing only its shell permission makes the same model request succeed.

This narrows the failure to the Console free-tier client classifier rejecting the built-in explore read-only tool set, rather than model selection or prompt identity. Both agents use the same client-header construction in packages/core/src/session/model-request.ts. Adding shell to explore would weaken its intentional read-only boundary, so the classifier should recognize the official explore tool signature instead.

Same class of bug, different built-in agent: plan.

Environment: opencode v2.0.8, Linux (official install), Zen free tier (provider Console), no plugins, no other config.

Reproduction (consistent, 100% of attempts, also with --standalone):

Add to opencode.json:
"agents": { "plan": { "permissions": [ { "action": "shell", "resource": "*", "effect": "deny" } ] } }
opencode run --standalone --agent plan "hi"
→ Error from provider (Console): OpenCode's free tier can only be used from within OpenCode

Test matrix — same binary, same server, same free-tier models (muse-spark-1.3-contributor-free, big-pickle):

Agent config	Result
plan, no override	✅ works
plan + permissions (even one deny rule)	❌ gate error
plan + description only	✅ works
plan + model only	✅ works
build + permissions override	✅ works
custom agent (any, e.g. reviewer)	❌ gate error

Impact: the documented way to lock down the plan agent (agents.plan.permissions) makes that agent unusable on the free tier. Like the explore case, the gate accepts some request paths and rejects others, inside the same CLI.

Workaround for now: drop the agents.plan.permissions override (built-in plan already denies edits outside ~/.opencode/plan and asks before shell commands).

I'm hitting the same issue on v2.0.8 (official CLI).

Reproduction:

Main session uses OpenCode Zen free models — works fine.

explore subagent with the same models fails immediately with:

Error from provider (Console): OpenCode's free tier can only be used from within OpenCode

general subagent with identical models succeeds without issues.

Confirmed multiple explore invocations failed; general invocations succeeded with the same model IDs.

Workaround is using general in place of explore, which works but loses the read-only exploration intent.

Looking forward to the fix. 👀

Removing "bash": "deny" from my agent config fixed it for me.

Free Zen models fail with a client-identity error, but only on subagent requests. The primary agent (paid opencode-go) works fine.

Error:
AI_APICallError: OpenCode's free tier can only be used from within OpenCode

Environment:

OpenCode 1.18.30 (npm), Linux (NixOS, KDE Plasma 6 / Wayland), Ghostty
Provider: OpenCode Zen, model opencode/big-pickle (free)
Plugin: @cortexkit/opencode-magic-context@0.34.2 (spawns background subagents via client.session.prompt)

Evidence (from ~/.local/share/opencode/log/opencode.log):

Free-tier errors today: 25
From mode=primary (main chat agent): 0
All from mode=subagent: dreamer-memory-mapper, dreamer, dreamer-retrospective, dream-verify
Sample: message="stream error" providerID=opencode modelID=big-pickle agent=dreamer-memory-mapper mode=subagent error.error="AI_APICallError: OpenCode's free tier can only be used from within OpenCode"

Timeline:

big-pickle used successfully since 2026-06-26 (no errors).
The free-tier client-check error appears for the first time on 2026-09-19.

Impact:
Background subagents cannot use any free Zen model at all, and each failed run surfaces the error to the user. Interactive free-tier use is also hit by "Free usage exceeded".

Removing "bash": "deny" from my agent config fixed it for me.

Just to clarify — removing "bash": "deny" isn’t really fixing the sub-agent issue. What it’s actually doing is granting the main agent the bash permission it was missing, which changes the request signature enough to pass the free-tier classifier.

The underlying problem is still there: the free-tier entitlement gate rejects sub-agent requests based on their tool/permission set, regardless of whether the sub-agent actually needs bash. The explore agent is intentionally read-only and should never have shell access, yet it fails with the same 403 — while general with identical models succeeds.

So the workaround "works" by sidestepping the classifier, but it doesn’t address the root cause: sub-agent requests should be classified the same as primary agent requests when using the same free-tier models from within the CLI.

I'm hitting the same issue on 2.0.11 (official CLI) Fresh Install.

have been facing the same issue.

Environment:
Arch Linux
Opencode2 v2.0.12
Model: mimo 2.6 flash free (using personal account/logged in)

Still broken in v2.0.14, with opencode/mimo-v2.6-flash-free.

Confirming the same trigger on my setup + minimal workaround.

Setup:

OpenCode 1.18.34 (opencode --version)
Windows 11
Custom project subagent (mode: subagent) that never needs bash (only reads .md/.typ and returns text)

Failing frontmatter (repro 3/3):

permission:
  read:
    "*": deny
    "**/*.md": allow
    "*.md": allow
  edit:
    "*": deny
    "**/*.md": allow
    "*.md": allow
    ".opencode/**": deny
  bash: deny
  question: allow

Error every time via task:

OpenCode's free tier can only be used from within OpenCode

Working frontmatter (repro 3/3 after restart):

permission:
  read:
    "*": deny
    "**/*.md": allow
    "*.md": allow
  edit:
    "*": deny
    "**/*.md": allow
    "*.md": allow
    ".opencode/**": deny
  bash:
    "*": deny
    "echo maquetador-noop*": allow
  question: allow

The agent never calls bash. Declaring a noop echo allow is enough to route correctly. This matches #50627 (34 vs 35 tools) and #52880.
Happy to add logs if a maintainer tells me which ones.

Reproduced on 2.0.26 / Windows, measured 2026-10-11. Same model opencode/space-bunny-free, same server run (run=7ce5f201 in opencode.log) for the main session and for all three subagents — so the passing child and the failing children ran in the same process:

agent	result
`general`	200, responds, no provider error
`explore`	`AI.Error: OpenCode's free tier can only be used from within OpenCode`
`scout`	same error

Two extra data points that may help narrow it down:

The error text is not present in any local artifact. Absent from the omniroute JS bundle, from the opencode JS, and from the 170 MB binary (findstr); ripgrep finds nothing either. The log's stack points at B:/~BUN/root/chunk-nqcdhx9v.js:6:3619. So the string arrives from the server rather than from client-side tier policy.
scout fails identically to explore. The original report covers explore vs general; the failure extends to scout as well, which points at "free tier refused by agent route" rather than by tier.

Reconnecting the account after the failure changed nothing — explore was retested post-login and returned the same error.

fix: cite the open opencode issue and add the shell permission key (#149

Thanks for the detailed comparison between explore and general. We couldn't reproduce this in our sandbox. The error comes from OpenCode Zen's free-tier check on the server, and our test environment is already over the free usage limit, so every free-model request was rejected before it reached that check.

One difference we found in the code, though we haven't confirmed it causes this: explore is the only built-in subagent with its own system prompt, and that prompt replaces the default OpenCode one, while general keeps the default. The request headers are the same for both. A maintainer with free-tier access will need to confirm whether that is what trips the check.

Until then, using general for exploration, as you did, is a reasonable workaround.

docs: document the free-model limitation and release 0.3.0

Linking my comment from #50627 because it's a different repro path but still relevant here.

Navigation Menu

Repository navigation

subagents: explore agent denied free tier can only be used from within OpenCode while running inside the CLI — general works with identical models #49723

Summary

Environment

Reproduction

Models tried with `explore` (all FAIL with identical error)

Models tried with `general` (all SUCCEED)

Expected Behavior

Actual Behavior

Additional Context

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

subagents: explore agent denied free tier can only be used from within OpenCode while running inside the CLI — general works with identical models #49723

Description

Summary

Environment

Reproduction

Models tried with explore (all FAIL with identical error)

Models tried with general (all SUCCEED)

Expected Behavior

Actual Behavior

Additional Context

Activity

Dante-dan commented on Sep 18, 2026

Jean-Eudes commented on Sep 18, 2026

pamod-madubashana commented on Sep 19, 2026

rs1052 commented on Sep 19, 2026

pculler commented on Sep 19, 2026

pamod-madubashana commented on Sep 20, 2026

wiwatsrt commented on Sep 20, 2026

ShrekBytes commented on Sep 22, 2026

skaldebane commented on Sep 22, 2026

hymsoft commented on Oct 3, 2026

nz12two commented on Oct 11, 2026

opencodejr commented on Oct 28, 2026

cobrabr commented on Nov 4, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Models tried with `explore` (all FAIL with identical error)

Models tried with `general` (all SUCCEED)