OpenCode v2.3.0 shipped on November 13, 2026, and its headline change is one sentence long: subagents now return immediately, continue in the background, and report back whenever they become idle.
That sentence rewires how you drive the agent. Until now, delegating to a subagent was usually a blocking act: you asked, you waited, you got an answer. Now delegation is closer to sending a message — you keep working in the parent session while multiple subagents run concurrently, and each one reports back when it has something to say.
It is a small change to the mechanics and a large change to the workflow. This is a practical guide to the new model: what changed, the patterns it unlocks, and the sharp edges you should know about before you fan out five agents across your repo.
What actually changed
From the official v2.3.0 changelog, the core change (PR #63382):
Subagents now return immediately, continue in the background, and report back whenever they become idle. You can keep working in the parent session while multiple subagents run concurrently.
In practice, the lifecycle now looks like this:
sequenceDiagram
participant You
participant Parent as Parent session
participant ChildA as Subagent A (research)
participant ChildB as Subagent B (tests)
You->>Parent: Fix the flaky test + review auth.ts
Parent->>ChildA: Investigate auth.ts — returns session ID at once
Parent->>ChildB: Reproduce the flaky test — returns session ID at once
Parent->>You: Both delegated — keep working
ChildA-->>Parent: Report: findings when idle
ChildB-->>Parent: Report: reproduction when idle
Parent->>You: Both reports in — here's the summary
Three details matter:
- You get a session ID back immediately. The subagent call no longer blocks the parent on the child's work. The parent can delegate to several children in one turn and carry on.
- Reports arrive when the child goes idle. The child does its work, then reports to the parent — including, importantly, a fix in this same release: when a subagent goes idle while its own background work is still running, its report now says it is still running, so the parent waits for the final report instead of treating a partial answer as done (#63675).
-
Background is now the only mode. The release removed the subagent tool's
backgroundinput — there is no foreground option anymore. Every subagent is a background subagent.
One behavior change worth knowing, reported in the release discussion: pressing Escape on the parent no longer stops its running children. Stopping a child is now a per-child operation. That is the right design for background work — you would not want a stray keypress to kill a 10-minute investigation — but it means you need to know how to find and stop a child you no longer need. Do not assume Escape cleans up after you.
The quiet transcript
The second headline change is about noise. Transcript verbosity now defaults to low, which folds each run of tool calls and thoughts into one collapsible activity row. If you liked watching every step scroll past, set Verbosity to medium or high — or set session.verbosity in the TUI config. An existing session.verbosity setting is kept, so this only changes the default for people who never set one.
This pairs deliberately with background subagents. When three children are working at once, a transcript that shows every tool call from every agent would be unreadable. The low-verbosity default is the UI catching up with the concurrency model: summaries first, details on demand.
The desktop app also gains Jump to message — open it from the command palette or press Cmd+Alt+G (Ctrl+Alt+G on Windows and Linux) to search prompts across the current session and jump directly to one. In a long session with several delegated threads, that is the difference between finding a decision and scrolling for it.
Three patterns that actually work
Background subagents are a tool, not a strategy. Here are three patterns where the new model earns its keep — and what to watch for in each.
1. Fan-out research: one question, several angles
This is the strongest pattern. Give each subagent one independent, read-only question and let them run in parallel:
- "Map every place in this codebase where user input reaches a SQL query. Report file paths and line numbers only — do not change anything."
- "Find all the API clients in this repo and list which ones retry on failure and which ones do not."
- "Read the auth middleware and the session store. List the assumptions they make about token expiry."
Read-only tasks are the safest thing to parallelize: there is nothing to conflict, nothing to undo, and the reports compose neatly into one answer. If you are new to background subagents, start here.
2. Review while you code
Keep the parent session for your own work and send a child to review what you just wrote:
- "Review the diff on this branch for logic errors and missing edge cases. Do not fix anything — report findings with file and line."
The child reads while you keep typing. When its report lands, you have a second pair of eyes on code that is still fresh in your head. The key discipline: review-only. The moment the child starts editing files you are also editing, you have a merge problem with yourself.
3. Long-running checks that used to block you
Test suites, builds, lint passes over a large repo — the jobs you used to wait on. Delegate the run, keep working, get the report. Two release details help here: shell commands now survive server handoffs and keep their output when interrupted, and there is experimental support — behind the shell_timeout_background flag — for moving a shell command to the background when its timeout expires instead of killing it. With the flag on, an explicit timeout on a background command stops it.
A related behavior from v2.2.7 is worth knowing if you script OpenCode: opencode run now waits for the background shell commands, subagents, and image jobs its prompt started, then lets the model respond to their results before it exits. Scripts that relied on a blocking subagent answer will behave differently — the run prints that it is waiting for background jobs, and the report-triggered turn sets the exit code. If you have opencode run in CI or in a cron job, test it after upgrading rather than assuming identical behavior.
The sharp edges
Background concurrency is genuinely useful and genuinely capable of biting you. The hazards are not hypothetical — the retired third-party opencode-background-agents plugin documented the same ones from the plugin side before v2.3.0 made them native.
Concurrent edits are the big one. A background child can change files while you edit the same files in the parent. There is no lock, no merge step, and no undo that spans both sessions. The practical rule is simple: a task is either yours or the child's, never both at once. If you delegate an edit, stay out of those files until the report comes back. If you are mid-edit, delegate read-only work instead.
Background work you cannot undo is a real cost. A child that refactors enthusiastically for ten minutes while you are looking elsewhere can produce a diff that takes longer to review than the work would have taken to do yourself. Keep delegated edits small and scoped, and ask for a report before the next step rather than chaining big autonomous changes.
Idle does not mean done. The #63675 fix exists because a subagent could report while its own background work was still running, and the parent would treat the partial answer as final. The fix makes the report say "still running" in that case — but it is a reminder that in an asynchronous system, "I have something to say" and "I am finished" are different events. Read the report, not just the notification.
Know how to stop a child. With Escape no longer cancelling children, a runaway or mistaken delegation keeps running until you stop it per-child. Before you fan out five subagents, learn where that control lives in your client. Five background agents doing the wrong thing is worse than one foreground agent doing the wrong thing, because you will notice later.
Also in v2.3.0
The release is bigger than its headline. From the changelog:
-
Experimental MCP events, behind the
mcp_eventsflag — the runtime can now react to events from MCP servers rather than only calling them. -
Mutual-TLS client certificates for gateway providers — set
settings.tlswithcert,key, and an optionalpassphraseon the provider, with{file:}and{env:}values supported likeapiKey(#61832). If your model gateway requires client certificates, this removes a workaround. - LM Studio decision-model support, and local model discovery (Ollama, LM Studio, vLLM) now waits up to 15 seconds per request instead of 1, so remote or tunnelled endpoints actually list their models.
-
Code Mode gets simpler structured results from file and skill tools:
writeandeditreturn their confirmation as a string,patchreturns an empty result, andskillreturns the skill's directory and content. - Tool output truncation keeps the beginning of the output and preserves a usable preview if the full output cannot be saved; tail reads no longer load the entire file into memory.
- On the desktop side: an experimental Recent sessions sidebar (last seven days, 30 rows, hideable), Mermaid diagrams that can be maximized for zooming and panning,
Alt+Enterto place a follow-up first in the queue, and per-server terminal shell selection.
A short rules list for background subagents
If you take one thing from this release, make it a set of working rules rather than a feature list:
- Delegate read-only work first. Research, review, and mapping are where background subagents are pure win.
- One owner per file. Never edit the same files as a running child.
- Small scopes, reported back. Ask for findings before fixes, and for a report before the next step.
- Learn the stop control before you need it. Escape is not it anymore.
-
Test scripted runs after upgrading.
opencode runwaits for background jobs now, and exit codes follow the report turn.
The direction here is clear across the whole agent-tooling landscape: agents are becoming things you manage in parallel, not a single assistant you wait on. OpenCode 2.3.0 is one more step in that direction — and like every step in that direction, it rewards the people who treat delegation as a skill, not a button.
What do you think?
How are you using subagents — in OpenCode or any other agent tool? Do background-by-default subagents change how you work, or do you still prefer to watch one agent do one thing at a time? And what is your rule for deciding what is safe to delegate: read-only only, or do you trust a child with edits while you work elsewhere?
Sources
- OpenCode changelog, v2.3.0, 13 November 2026 (official release notes) — https://opencode.ai/changelog?area=desktop,core
- "OpenCode Background Subagents: What v2.3.0 Changes," Developers Digest, 13 November 2026 — https://www.developersdigest.tech/blog/opencode-2-3-background-subagents-quieter-transcripts-2026
- "Agent Tools Today (14 Nov 2026): Launches, Skills, MCP Servers" — https://munderdiffl.in/blog/agent-tools-today-2026-11-14/
Thanks for reading! I'm Shaswat Raj — I build CampusLoop, IndexFast, SopKit and open-source dev tools.
GitHub: https://github.com/playlikeboy/ · LinkedIn: https://www.linkedin.com/in/sh20raj/ · YouTube: https://youtube.com/@stackshade
Top comments (0)