Hands typing on a laptop showing code in an editor, illustrating a FreeAnswers guide to OpenCode 2.3 background subagents

OpenCode 2.3 Background Subagents: Power-User Guide to Setup, Permissions and Limits

by

Last updated: November 14, 2026

OpenCode 2.3, released November 13, 2026, makes every subagent run in the background. The subagent tool returns a session ID at once, children work concurrently, and each one reports back when it goes idle, so you can keep prompting in the parent session instead of waiting for delegated work to finish.

This guide is based on the OpenCode v2.3.0 release notes and the official OpenCode agents documentation. OpenCode is Anomaly’s open-source coding agent.

Contents

What changed in OpenCode 2.3

The v2.3.0 release, published on GitHub on November 13, 2026, lists three highlights. The first is the change to subagents: they “now return immediately, continue in the background, and report back whenever they become idle.” The release notes add that you can keep working in the parent session while multiple subagents run concurrently.

The second highlight is quieter transcripts. The terminal interface (TUI) now summarizes each run of tool calls and thoughts into one collapsible activity row. The third is Jump to message in the desktop app, which searches the prompts in the current session.

The table summarizes the new behavior. If you skipped the October releases, our OpenCode 2.2 guide covers /goal and desktop plugins.

Area OpenCode 2.3 behavior
Subagent launch The tool returns the child session ID immediately; work continues in the background
Results The child reports to the parent each time it goes idle, and again after later rounds of work
Concurrency Several subagents can run while you keep working in the parent session
Transcript Default verbosity is low: one activity row per run of tools and thoughts
Still-running children An idle report says when the child still has background work running, so the parent waits for the final report

How background subagents work

According to the agents documentation, subagents run with fresh context in their own child sessions. The parent receives a report when a child goes idle, and again after each later round of work. A subagent does not share the parent’s conversation, so the request you give it needs to contain everything it must know.

OpenCode ships two built-in subagents:

  • General (general) handles research and multi-step work with broad tool access, but cannot launch more subagents.
  • Explore (explore) searches and reads code or web sources without editing files.

The primary agents, Build and Plan, can delegate to them. For example: “Use the explore subagent to find every place we parse dates.”

The release also fixes a timing problem. When a subagent goes idle while its own background work is still running, its report now says it is still running. The parent then waits for the final report instead of treating the partial answer as done.

How to set up a custom subagent

  1. Update OpenCode. Run opencode upgrade, or install with npm install -g @opencode/cli or curl -fsSL https://opencode.ai/v2/install | bash, as listed in the OpenCode docs.
  2. Create an agent file. Save a Markdown file as .opencode/agents/reviewer.md in your project, or as ~/.config/opencode/agents/reviewer.md for all projects.
  3. Set the frontmatter. Add description, mode: subagent and, if you want, a model such as provider/model#variant. The Markdown body becomes the agent’s system prompt.
  4. Restrict tools. Add permissions rules, for example denying edit and shell for a read-only reviewer.
  5. Ask the primary agent to use it. Type a request such as “Use the reviewer subagent to review my current changes.” The call returns at once and the review continues in the background.
  6. Keep working and check in. Continue in the parent session. In the TUI, the default session.child.first key (down arrow) toggles the subagent picker, and left and right arrows move between child sessions. In the composer, Ctrl+D interrupts the selected subagent.
  7. Read the reports. Each child reports to the parent when it goes idle. Review the result before you act on it.

Add a clear description to every subagent. The documentation notes that OpenCode shows it to the model when it chooses which agent to launch.

Permissions, depth and models

The documentation lists these controls:

Control Where What it does
subagent permission rules Parent agent’s permissions Control which agents the parent may launch, for example deny * and allow reviewer
Child permissions Subagent’s own definition The child uses its own configured permissions, not the parent’s
experimental.subagent_depth opencode.jsonc How deeply subagents can start their own subagents; default 1 means a subagent cannot start another
model Agent definition Sets the subagent’s model; without it the child inherits the parent session’s model
steps Agent definition Maximum model steps; on the final step OpenCode removes tools and asks for a text summary

Permission rules are ordered, and the last matching rule wins, so put broad rules before exceptions. The configuration documentation warns that experimental settings such as subagent_depth may change, break or be removed in any release.

Other changes in 2.3

  • Verbosity. Set Verbosity to medium or high in settings, or set session.verbosity in your TUI config, to see every step again. The keybinds reference also lists an unbound session.verbosity.cycle action you can assign.
  • Jump to message. In the desktop app, press Cmd+Alt+G on macOS or Ctrl+Alt+G on Windows and Linux.
  • MCP events. Experimental support for MCP events, behind the mcp_events flag.
  • Shell timeouts. An experimental shell_timeout_background flag moves a shell command to the background when its timeout expires.
  • Mutual TLS. Providers can present a client certificate through settings.tls with cert, key and an optional passphrase.
  • Local models. Discovery for Ollama, LM Studio and vLLM now waits up to 15 seconds per request instead of 1, and LM Studio decision models are supported. Our LM Studio Bionic guide covers LM Studio’s agent app.
  • Code Mode. File and skill tools return simpler structured results. A similar idea appears in Anthropic’s tool, covered in our Claude Code Code Mode guide.

Limits and things to watch

  • No opt-out described. The release notes and documentation say subagents always run in the background; neither describes a switch back to waiting.
  • Fresh context. Children do not see the parent conversation, so vague requests produce vague results.
  • Hidden is not secure. The hidden option removes an agent from listings but, as the docs state, controls visibility, not security.
  • Request overlays. Per-agent request headers and body values are preserved but not yet sent with model requests in the V2 session runner.

For other approaches to parallel agents, see our Antigravity Dynamic Workflows guide and our pi coding agent 1.5 guide.

Frequently asked questions

What changed with subagents in OpenCode 2.3?

In OpenCode v2.3.0, released November 13, 2026, subagents always run in the background. The subagent tool returns the child session ID immediately, and each subagent reports to the parent session when it becomes idle, so you can keep working while several subagents run at once.

Can I turn background subagents off in OpenCode?

The v2.3.0 release notes and the OpenCode agents documentation say subagents always run in the background. Neither source describes a setting that restores the earlier waiting behavior. You can limit which subagents an agent may launch with subagent permission rules.

Can a subagent start its own subagents?

Not by default. The experimental subagent_depth setting defaults to 1, so a subagent cannot start another subagent. Setting it to 2 allows one more level. Experimental settings may change or be removed in any release.

Which model does an OpenCode subagent use?

A subagent uses the model set in its own agent definition, written as provider/model with an optional #variant. If no model is configured, it inherits the parent session’s model.

How do I see every tool call again after updating to 2.3?

OpenCode 2.3 sets transcript verbosity to low by default, which folds tool calls and thoughts into one activity row. Set Verbosity to medium or high in settings, or set session.verbosity in your TUI config. A value you already set is kept.

Sources

Related guide: Cloudflare Kitesurf guide.

Related answers

Leave a Comment