OpenCode 2.3 hands-on: subagents, timed-out commands, and compaction now run in the background

Published on November 18, 2026 by Remy

Short answer: OpenCode 2.3.0 (November 13) and 2.3.1 (November 18, 00:17 UTC) stop making you wait in three places. A subagent call returns immediately, and the result arrives when the subagent goes idle. A shell command that reaches its timeout moves to the background instead of being killed. When a session nears automatic compaction, the summary is already written in the background, so the swap is instant.[1][2] Most setups need no changes. Check these cases:

If this is youDo this
You installed with npm i -g opencode-aiThat package only ships 1.x and stops at 1.19.6. Version 2 is @opencode/cli: run npm i -g @opencode/cli, or curl -fsSL https://opencode.ai/v2/install | bash.[3]
You rely on a timeout to stop a commandA timeout now moves the command to the background. To enforce a limit, put timeout 60 <cmd> in the command itself. A foreground timeout: 0 now means the 120-second default.
Your config sets experimental.background_compaction or the shell_timeout_background flagThe first is removed. Use compaction.background, which defaults to true. The flag is gone, and configs that still set it keep loading.
You don’t want to pay for summaries that never get usedSet "compaction": { "background": false } in opencode.jsonc.
Your project only has a CLAUDE.md2.3.1 reads it again. Set OPENCODE_DISABLE_CLAUDE_CODE=1 to skip it.

Other harnesses make different default choices for the same three mechanisms:

Shell command timeoutSubagentsAuto-compaction
OpenCode 2.3.1Moves to background, notifiesAlways background, reports when idleSummary starts 60k tokens early
Claude Code 2.1.327Moves to background, except sleep-firstBackground by defaultAt the context limit, plus idle compaction
Codex CLI 0.169.1Returns a session ID, model pollsSpawned on request, main thread waitsModel default limit, async_compaction off
Gemini CLI 0.68.0Ends after 300 s without outputCalled as a tool, parent waitsAt 50% of context
Qwen Code 0.28.0Ends at 120 sBackground by default, notifiesAt about 85%

This is the first issue of the Agent Harness series. OpenCode is the main thread, with a look at how the other harnesses handle the same mechanism. OpenCode was last on this site because of the Console breach: After the OpenCode breach: why coding agents became credential magnets.

Version 1 and version 2 are now separate npm packages

The test box had 1.18.31 from the opencode-ai npm package. That package’s latest tag is 1.19.6, so npm update never reaches 2.x. OpenCode 2 ships as @opencode/cli. The v1 install script refuses 2.x versions and points to https://opencode.ai/v2/install or opencode upgrade --major.[3]

Switching from opencode-ai 1.18.31 to @opencode/cli 2.3.1: opencode-ai tops out at 1.19.6, the new package reports opencode v2.3.1, and its binary hash matches the GitHub release asset

Remove opencode-ai first, because both packages claim the opencode command. npm warns that install scripts did not run. That doesn’t matter here: the installed binary has the same hash as the one in the opencode-linux-x64.tar.gz release asset. Version 2 starts a background service that the CLI talks to. opencode run --standalone instead starts a private server and stops it on exit. That difference matters for the compaction test below.

Every test ran with its own XDG_* directories, with no paid account connected, on free models listed by OpenCode Zen.

Three things that now run in the background (timed on the test box)0 s5 s10 s15 s20 sSubagentParent: task returns at once, writes parent.txt at 09:04:55Child: sleep 15, then writes sub.txt (09:05:10)report delivered when the child goes idleShell timeoutforeground, timeout 5 smoved to the background, output streams to a file<shell state=completed> wakes the sessionCompactionthreshold(not on the time axis)summary in backgroundbackground on (default): summary already writtenanswer starts 0.03 s after compaction5.3 s waitbackground: false: summary written at the thresholdTimes come from the three opencode run sessions in this post. The compaction rows replay the same inputs under both settings.

Figure: the three background changes as timed on the test box. The subagent and shell rows use the time axis. The compaction rows compare the same inputs under the two settings.

Subagents: the call returns now, the report comes later

Before 2.3.0, a parent session waited for its subagent to finish. Now the subagent tool returns a session ID right away and the child keeps working. Each time the child goes idle, the parent receives a <subagent> message, and it gets another one after each later round of work.[1] The tool result tells the model plainly what to do next. Don’t sleep, don’t poll, and don’t duplicate the child’s work. Do something that doesn’t overlap, or tell the user what you launched and end the turn.

glm-5.3-flash-free starts a general subagent: the task tool returns a session ID at once, the parent writes parent.txt at 09:04:55, and the child sleeps 15 seconds, writes sub.txt at 09:05:10, and reports back

In the test the child ran sleep 15 and then wrote a timestamp. The parent wrote its own timestamp as soon as the tool returned. parent.txt says 09:04:55 and sub.txt says 09:05:10, exactly one sleep apart. When the parent’s turn ended, opencode run didn’t exit. It printed waiting for 1 background job and resumed the turn when the report arrived. Scripts and CI jobs that call opencode run therefore don’t get a half-finished answer while a child is still running.

A child can start background work of its own, such as a long command that moved to the background, and then go idle. Since 2.3.0, the report in that case says the child is still running, so the parent waits for the final report instead of treating a partial answer as done.[1] 2.3.1 fixes a related bug: a child whose answer quoted the “Background work still running” heading was reported as still running.[2]

The gain is that the parent no longer sits idle, and it can run several unrelated children at once. There are two costs. Concurrency means several contexts spend tokens at the same time. And the model has to learn to launch and move on. Prompts that say “wait for the subagent, then…” still work, but the runtime does the waiting, not a model that sleeps. Permission prompts from a subagent now appear while you view its session. Rejecting one request rejects only the other requests from the same step, not every pending request in the session.[2]

Shell timeouts: the command keeps running

This is the most practical change in 2.3.1. A shell command that is still running at its timeout now moves to the background in every build. Output keeps streaming to a file, and when the command exits, the session wakes up with the result. In 2.3.0 this sat behind the experimental shell_timeout_background flag. 2.3.1 makes it the default and removes the flag. Configs that still set it keep loading.[1][2]

deepseek-v4.1-flash-free runs sleep 20 with a 5000 ms timeout: the tool result says Command moved to the background with a shell ID, PID, and output file, a state=completed report arrives 20 seconds later, and done.txt exists

The test command was date +%T; sleep 20; date +%T; echo SLEEP-DONE > done.txt with a 5-second timeout. At 5 seconds the tool returned “Command moved to the background” with the shell ID, the PID, and the output path, plus a warning not to start a second copy. Twenty seconds in, the session received <shell id=... state="completed"> with the two timestamps 09:04:07 and 09:04:27, and done.txt was on disk.

Two related changes ship with it:

  • A foreground timeout: 0 used to mean “wait until it exits”. It now means the 120-second default, and the command moves to the background when that expires.
  • The process daemon now cleans up finished commands, so they no longer leave zombie processes under opencode-pty. Processes that a successful command started with cmd & keep running. Leftovers from a failed command are stopped.[2]

I think this is the right default. When a build or test run gets killed at its timeout, the model usually tries again with different flags and wastes several more minutes. A command that moves to the background runs once and still reports its result.

Keep one side effect in mind: a timeout no longer stops anything. Database migrations, outbound requests, and writes to shared directories used to die at the timeout. Now they run to completion. If you used the timeout as a safety stop, put an explicit timeout in the command or block it with a permission rule.

Background compaction: the summary is ready before you need it

What compaction does hasn’t changed. Near the model’s context limit, OpenCode summarizes the conversation, keeps about 15k recent tokens verbatim, and drops the older turns.[4] What changed is when the summary gets written.

It used to be written at the threshold, and your next prompt waited for it. In 2.3.1 the summary starts 60k tokens before the threshold, runs in the background, and is held in memory while the session continues. At the threshold, OpenCode swaps it in and keeps everything after it as is.[2][4]

Where background compaction sits in the context windowmodel context window (128k)0 – 48.8k60kbuffersummary starts 60k before the thresholdthreshold = window − bufferbuffer: 15% by default, at least 16kthe finished summary is held in memory while the session continuesat the threshold the held summary is swapped in; ~15k recent tokens stay verbatimgrowth past ~40% of the threshold since the summary, or a changed prefix → normal compactionsmall windows: start no earlier than halfway from the first post-compaction reply to the thresholda restart drops held summaries; an unused summary is still billedExample: 128k window, 19.2k buffer → compacts at ~108.8k, starts writing at ~48.8k

Figure: where background compaction starts and when it falls back. The threshold is the window minus the buffer, which defaults to 15% of the window and at least 16k. Based on the OpenCode Compaction docs.[4]

The docs spell out the edges:[4]

  • If the conversation grew past about 40% of the threshold since the held summary, or the start of the conversation changed, OpenCode drops the held summary and compacts normally.
  • On small windows, the summary starts no earlier than halfway between the first response after the last compaction and the threshold.
  • Held summaries live in memory and are lost on restart. Provider-side native compaction doesn’t use this path.
  • After a model switch, or after a break longer than the prompt cache lifetime, the summary starts from the next response instead.
  • The summary request reuses the prompt cache, but an unused summary is still billed. If the session ends before the threshold, those tokens bought nothing.

To reach compaction in a few turns, the test set the context window of mimo-v2.6-flash-free to 48000 in the project config. The buffer then falls back to its 16k minimum, so the threshold is about 32k. Turn one attached a release-notes file. Turn two attached three more files and brought the context to about 23k. After a 40-second pause, turn three attached about 11k tokens of JSON and crossed the threshold. The same three turns then ran in a second directory with "compaction": { "background": false }. Both sessions ran through the background service, because --standalone would discard the held summary on every exit.

Message timelines for both sessions: with the default setting the assistant starts 0.03 seconds after the compaction record, with background set to false it starts 5.3 seconds after

The timelines come from the session database. With the default setting, the compaction record (reason=auto, status=completed) appears 0.02 seconds after the third prompt, and the assistant starts 0.03 seconds later. The summary was already done. With background compaction off, the assistant starts 5.3 seconds after the compaction record. Those 5.3 seconds are the summary being written on the spot.

Longer contexts take longer to summarize, so the saving grows with the session. The price is the extra summary request. If your sessions are usually short, or you count every token, turning it off is reasonable.

CLAUDE.md is read again

2.3.1 restores compatibility with Claude Code’s file conventions. In a directory with no AGENTS.md but a CLAUDE.md, OpenCode reads CLAUDE.md. When the global ~/.config/opencode/AGENTS.md is missing, it falls back to ~/.claude/CLAUDE.md. The same rules apply to instructions the agent finds while reading nested files. Set OPENCODE_DISABLE_CLAUDE_CODE or OPENCODE_DISABLE_CLAUDE_CODE_PROMPT to skip every CLAUDE.md.[2][5]

Four directories: with only CLAUDE.md the answer is PELICAN-CLAUDE-MD, with OPENCODE_DISABLE_CLAUDE_CODE=1 it is NONE, with both AGENTS.md and CLAUDE.md it is HERON-AGENTS-MD, and with no project file but a .claude/CLAUDE.md under HOME it is GLOBAL-CLAUDE-HOME. The instruction records in the session database match

Each instruction file held a different codeword, and the model had to answer from its instructions without using tools. All four answers match the rules. An answer alone isn’t proof, since a model can go read the file itself. The last command in the screenshot lists the instruction files that each session actually loaded, from the session database. They match the answers, and the session with the environment variable set loaded no instruction file at all.

For teams coming from Claude Code, this means no duplicate AGENTS.md just for OpenCode. When both files exist, OpenCode reads only AGENTS.md. It doesn’t merge them.

Smaller changes worth knowing

  • The TUI is quieter by default. 2.3.0 folds each run of tool calls and thoughts into one activity row. To see every step, set Verbosity to medium or high in settings, or set session.verbosity in the TUI config. A value you already set is kept.[1]
  • Schedules are now automations. The experimental endpoints are /api/experimental/automation and client.experimental.automation.*. The schedule endpoints are removed.[2]
  • ChatGPT sign-in adds GPT 6.2 Sol and GPT 6.2 Astra, plus their fast variants.[2]
  • read pages small files too, using the default line and byte limits. limit: 0 is now an error.[2]

How the other harnesses handle the same three things

Same three mechanisms, five harnesses, default behaviorShell command timeoutSubagentsAuto-compactionOpenCode 2.3.1moves to background120 s defaultalways backgroundreports when idlesummary 60k earlyswapped in at thresholdClaude Code 2.1.327moves to backgroundexcept sleep-firstbackground defaultfork mode, can turn offat the context limitplus idle compactionCodex CLI 0.169.1returns a session IDmodel polls write_stdinspawn on requestmain thread waitsmodel default limitasync_compaction offGemini CLI 0.68.0killed after 300 s quietis_background to detachcalled as a toolparent waitsat 50% of contextinlineQwen Code 0.28.0ends at 120 sis_background to detachbackground defaultnotifies on finishat about 85%inlinebackground by default, notifiespartly background or polledblocks, kills, or compacts inlineBased on each project's docs, release notes, and defaults in the installed packages. Sources at the end.

Figure: default behavior of five harnesses for the three mechanisms. Green means background by default with a notification, amber means partly background or polled, and gray means the harness blocks, kills the command, or compacts inline.

Claude Code 2.1.327 is closest to OpenCode. A foreground Bash command times out after 2 minutes by default and then moves to the background, unless it starts with sleep. A moved command has no time limit in an interactive session. Unattended sessions such as -p give it 30 minutes from the move, or 10 minutes for a -p run with a text prompt.[6] Subagents launched from the main conversation start in the background. To let Claude wait for one, set CLAUDE_CODE_FORK_SUBAGENT to 0.[7] Compaction is where the two differ most. Without a configured window, Claude Code compacts at the model’s context limit, at about 967K for models with a native 1M window. It also has idle compaction: a conversation over 200,000 tokens that you leave for about an hour is compacted before the prompt cache expires, so your next message sends a summary.[8][9] Both projects hide the wait. OpenCode does it just before the threshold, and Claude Code does it while you’re away. CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 turns all of this off, and timed-out commands are stopped again.[10]

Codex CLI 0.169.1 takes a different route. With unified exec, which is on by default, a command that is still running after a short wait returns its session ID and the output so far, and the process keeps going. The model then reads more output through write_stdin, and an empty poll waits at most 5 minutes (background_terminal_max_timeout).[11] That is polling, not notification. Codex spawns subagents when you ask for them or when project or skill instructions request it. The docs say Codex waits until all requested results are in before giving one consolidated answer.[12] Auto-compaction uses model_auto_compact_token_limit, or the model’s default when unset.[11] On the test box, codex features list shows async_compaction and wake_on_agent_messages as under development and off, and the changelog includes entries such as “Add a root-only option for background compaction”.[13] Codex is building both background compaction and agent wake-ups. Neither is on by default yet.

Gemini CLI 0.68.0 is the most conservative. To run a command in the background, the model has to set is_background: true when it calls the shell tool. A foreground command with no output for 300 seconds is ended (tools.shell.inactivityTimeout).[14] Subagents appear to the main agent as tools of the same name, and the call returns when the subagent reports back.[15] Compression triggers at 50% of the context (model.compressionThreshold), much earlier than the others, and runs inline.[16]

Qwen Code 0.28.0 forked from Gemini CLI and now sits halfway between Gemini and Claude Code. Its shell tool works like Gemini’s: background runs need an explicit is_background: true, and a foreground command ends at the 120-second default, which tools.shell.defaultTimeoutMs changes.[17][18] Its subagents work like Claude Code’s: top-level subagents run in the background by default and send their result to the main session as a notification. agents.defaultBackground: false brings them back to the foreground.[19] Auto-compaction targets about 85% of the window and fires earlier on small windows to leave room for the summary.[18]

Locally installed Claude Code 2.1.327, Codex CLI 0.169.1, Gemini CLI 0.68.0, and Qwen Code 0.28.0: --autocompact in claude --help, async_compaction and wake_on_agent_messages false in codex features list, a 0.5 compression threshold and a 300-second shell inactivity timeout in the Gemini package, DEFAULT_PCT 0.85 and AUTOCOMPACT_BUFFER 13000 in the Qwen package

Put side by side, the direction is clear. Background subagents are now the default in OpenCode, Claude Code, and Qwen Code. OpenCode and Claude Code move timed-out commands to the background, while Gemini CLI and Qwen Code still end them. Only OpenCode writes the compaction summary early by default. Codex has a flag for it that is off. The remaining split is how background results come back. OpenCode, Claude Code, and Qwen Code wake the session with a notification. Codex has the model poll. Notifications save tokens and stop the model from sleeping in a loop, but the runtime must be able to restart a session after its turn has ended. The 2.3.1 fix for “ACP clients missing turns that a background shell woke after the original turn ended” is exactly that kind of problem.[2]

What background work makes harder

All three changes take the wait out of your view. They also create new problems.

Cost is harder to predict. Concurrent subagents and early summaries are token spend you didn’t ask for directly. If you pay per token, watch opencode stats for a week or two. When Claude Haiku 5.5 actually saves money as a subagent or compaction engine has a cost model you can fill in with your own numbers. For governing these defaults in a company, see Control the Harness, Control the Cost.

Side effects are harder to contain. A timeout no longer stops a command, and background commands and subagents can keep editing files or sending requests after you think the turn is over. An audit has to cover the background task list and the output files, not just the transcript.

Debugging is harder. One answer can depend on three results that arrived at different times: a subagent report, a background shell completion, and a summary written early. When something goes wrong, establish the order first. The session_message table in the session database records each message’s type and time. The timelines in this post come from there.

What was tested and what wasn’t

Tested (OpenCode 2.3.1, Linux x64, free models, isolated XDG_* directories):

  • The switch from opencode-ai 1.18.31 to @opencode/cli 2.3.1, with a hash that matches the GitHub release.
  • Background subagents: the call returned at once, the parent wrote its timestamp first, and the child’s report arrived 15 seconds later.
  • Shell timeout: a 20-second command with a 5-second timeout moved to the background and reported on completion.
  • Background compaction: with the model window set to 48k, the wait was 0.03 seconds with compaction.background on and 5.3 seconds with it off.
  • CLAUDE.md fallback: project level, global level, AGENTS.md precedence, and the disable variable.
  • The other four harnesses: Claude Code 2.1.327, Codex CLI 0.169.1, Gemini CLI 0.68.0, and Qwen Code 0.28.0 installed in a scratch directory, with --help, features list, and package defaults checked.

Not tested, described from docs and release notes only:

  • The TUI’s session.verbosity and folded rows. The tests used opencode run only.
  • A foreground timeout: 0 meaning 120 seconds.
  • The “still running” report from a child with its own background work, and subagent permission prompts.
  • The automations endpoints.
  • Real sessions in the other four harnesses. None of them was signed in.
  • Free models have usage limits. One run printed “Free usage limit reached” after it had answered. With your own model and window size, summary times will differ.

Sources

  1. OpenCode v2.3.0 release notes: https://github.com/sst/opencode/releases/tag/v2.3.0 (PRs #63382, #63675, #63024, #63207) ↩
  2. OpenCode v2.3.1 release notes: https://github.com/sst/opencode/releases/tag/v2.3.1 (PRs #63699, #64290, #64266, #64026, #64474, #64533, #64343, #64160, #64262) ↩
  3. OpenCode install scripts: https://opencode.ai/install (v1) and https://opencode.ai/v2/install (v2). npm package @opencode/cli ↩
  4. OpenCode docs, Compaction: https://opencode.ai/v2/docs/compaction ↩
  5. OpenCode docs, Rules: https://opencode.ai/v2/docs/rules ↩
  6. Claude Code docs, Tools reference (timeouts and background time limits): https://code.claude.com/docs/en/tools-reference ↩
  7. Claude Code docs, Subagents: https://code.claude.com/docs/en/sub-agents ↩
  8. Claude Code docs, Model configuration (auto-compact window): https://code.claude.com/docs/en/model-config ↩
  9. Claude Code docs, Settings reference (idleCompaction): https://code.claude.com/docs/en/settings-reference ↩
  10. Claude Code docs, Environment variables: https://code.claude.com/docs/en/env-vars ↩
  11. Codex docs, Configuration reference: https://developers.openai.com/codex/config-reference ↩
  12. Codex docs, Subagents: https://developers.openai.com/codex/subagents ↩
  13. Codex changelog: https://developers.openai.com/codex/changelog ↩
  14. Gemini CLI docs, Shell tool: https://geminicli.com/docs/tools/shell/ ↩
  15. Gemini CLI docs, Subagents: https://geminicli.com/docs/core/subagents/ ↩
  16. Gemini CLI docs, Configuration: https://geminicli.com/docs/reference/configuration/ ↩
  17. Qwen Code docs, Shell tool: https://github.com/QwenLM/qwen-code/blob/v0.28.0/docs/developers/tools/shell.md ↩
  18. Qwen Code docs, Settings: https://github.com/QwenLM/qwen-code/blob/v0.28.0/docs/users/configuration/settings.md ↩
  19. Qwen Code docs, Sub-agents: https://github.com/QwenLM/qwen-code/blob/v0.28.0/docs/users/features/sub-agents.md ↩