OpenCode 2 v2.2.6: worktree runs, archived sessions, shared MCP pools#

Published November 7, 2026 by Alex Sorokoletov

Part of the OpenCode 2 Version Tracker series. | OpenCode on GitHub | OpenCode 2 docs

OpenCode 2 v2.2.6 extends v2.2.5 and reshapes opencode run for scripts and CI. A run can start in a fresh git worktree with -w, stay out of your inbox with --archived, and wait for the background jobs its prompt started before it exits. MCP servers gain opt-in connection pooling through pool: true, and OPENCODE_FLAGS switches experimental features on from the environment.

opencode run for scripts and CI#

opencode run -w (or --worktree) starts the session in a new git worktree, and --worktree=<name> sets the worktree name. It cannot be combined with --continue or --session (#60712). opencode run --archived creates the session already archived, so scripted and CI runs stay out of the inbox, home, and session lists, stay hidden from the TUI session list, and are skipped by --continue (#61270).

The run also waits for the background shell commands, subagents, and image jobs its prompt started, then lets the model respond to their results before it exits. While waiting it prints waiting for N background job(s), delivered as a background_wait event under --format json (#60699, #61911). There is no time limit, so a job that never exits, such as a dev server or file watcher, holds the run open until Ctrl+C or SIGTERM. SIGTERM cancels the session and its background jobs and exits with code 143 (#61911, #61721).

Environment flags and MCP pooling#

Set pool: true on an MCP server to share one connection across projects with the same setup (#61185). Session warming gained provider- and model-specific settings, including an interval: "auto" mode keyed to the model's cache TTL (#60025, #60969). Permission policy adds a websearch.use action (#61557).

Two config flags preview work in progress:

Server and fetch hardening#

The server API serves file reads and media as sandboxed downloads and refuses cross-site browser navigations and requests from disallowed origins to /api/*, so a file in your project cannot run scripts on the server's origin (#62422). Webfetch and the Code Mode fetch reject URLs that contain credentials and ignore the #fragment when matching permission rules, and Code Mode fetch checks every redirect against your webfetch rules (#60502, #61701, #62373). A session_move that leaves the current project now asks for external_directory permission first (#62204).

GUI plugins and the jobs SDK#

GUI plugins can contribute color themes through a Theme registry (#61485), register custom fenced-code rendering and actions through CodeBlock and CodeBlockAction registries (#61533), build native-looking interfaces with ctx.ui.Select, settings-layout, and menu-row components (#61527), and set, read, and persist a side panel's preferred width (#61509). On the SDK side, client.experimental.job.list() and its Effect equivalent list background shell, subagent, and image jobs with session, descendant, kind, and status filters (#60698), and a server embedder can supply its own fetch for OpenCode HTTP, model, web, and remote MCP traffic (#61582).

The run command now owns its background work#

Worktree isolation, pre-archival, background-job waiting, and exit code 143 move the whole lifecycle of a prompt's work under opencode run. A clean exit now means the model already saw the results of the background shell commands, subagents, and image jobs the prompt launched, which is a stronger guarantee for a CI step to build on than a command that returns once the model stops typing.

The open edge is the job that never exits. With no built-in time limit, the caller's own timeout becomes the only bound on a run, and the background_wait event under --format json is the signal that separates a run doing useful waiting from one that has hung on a dev server or watcher.

All trademarks and software referenced belong to their respective owners.