Agent Breaking Changes_

← OpenCode

OpenCode v2.2.0

breakingmodel

2026-10-27 · official notes

Summary

Full notes

### Highlights

- Create, install and share [Desktop plugins](https://opencode.ai/v2/docs/build/plugins/gui) (experimental) ([#55246](https://github.com/anomalyco/opencode/pull/55246), [#59469](https://github.com/anomalyco/opencode/pull/59469), [#59489](https://github.com/anomalyco/opencode/pull/59489))
- Refreshed the desktop app experience ([#56898](https://github.com/anomalyco/opencode/pull/56898), [#58865](https://github.com/anomalyco/opencode/pull/58865), [#55838](https://github.com/anomalyco/opencode/pull/55838), [#57962](https://github.com/anomalyco/opencode/pull/57962))
- Add experimental image and decision generation APIs to plugins and sdk, allowing image generation or decision model (think typesafe, clef, etc) workflows. ([#59190](https://github.com/anomalyco/opencode/pull/59190), [#59380](https://github.com/anomalyco/opencode/pull/59380), [#58758](https://github.com/anomalyco/opencode/pull/58758))
- Plugins can now attach and update keyed session instructions with ctx.session.instructions.entry.put/list/remove. Instead of editing the system prompt and busting the prompt cache, each change is added as a small update at the next step. The entries also survive compaction and reverts, and they don't start an extra model turn. ([#56550](https://github.com/anomalyco/opencode/pull/56550))
- Restored the Todo tool in desktop via opt-in ([#59092](https://github.com/anomalyco/opencode/pull/59092))
- Add configurable prompt cache TTLs per provider/model ([#59157](https://github.com/anomalyco/opencode/pull/59157))

### Breaking changes

#### `@opencode/ai` root is now the Promise API

`@opencode/ai` now works like `@opencode/sdk` and `@opencode/client`: the package root exports the Promise API, and the Effect API moved to `@opencode/ai/effect`. `@opencode/ai/promise` is removed, and the wildcard subpath export is replaced with an explicit list of provider and protocol entry points. ([#58847](https://github.com/anomalyco/opencode/pull/58847), [#59183](https://github.com/anomalyco/opencode/pull/59183))

```diff
-import { AI } from "@opencode/ai/promise"
-import { LLM } from "@opencode/ai"
+import { AI } from "@opencode/ai"
+import { LLM } from "@opencode/ai/effect"
```

#### The OpenCode GitHub Action is removed

The OpenCode GitHub Action is no longer published. Remove it from your workflows. ([#59032](https://github.com/anomalyco/opencode/pull/59032))

#### TUI plugins require OpenTUI 0.7

`@opencode/plugin` now requires `@opentui/core` and `@opentui/solid` 0.7.0, up from 0.6.8 or later. Plugins that depend on OpenTUI 0.6 fail to install until they upgrade. In OpenTUI 0.7, custom renderables read their hooks from their class at construction: assign `renderBefore`, `renderAfter`, and `onLifecyclePass` in the constructor instead of as class fields, call `refreshHooks()` after adding a hook by reflection, and replace `defineNativeIntegration()` with a `static nativeIntegration` declaration. See the [OpenTUI 0.7.0 release notes](https://opentui.com/docs/releases/0.7.0). ([#59295](https://github.com/anomalyco/opencode/pull/59295))

### Core

#### Improvements

- Add experimental image and decision generation API endpoints. ([#59190](https://github.com/anomalyco/opencode/pull/59190))
- Add image and decision entrypoints for catalog providers. ([#59380](https://github.com/anomalyco/opencode/pull/59380))
- Improve integration rebuild performance. ([#59402](https://github.com/anomalyco/opencode/pull/59402))
- Let custom model configuration set a model type. ([#59388](https://github.com/anomalyco/opencode/pull/59388))
- Let model-list API requests filter by type. ([#59355](https://github.com/anomalyco/opencode/pull/59355))
- Make external-directory permission checks use the project's filesystem. ([#59089](https://github.com/anomalyco/opencode/pull/59089))
- Reduce memory use when code search finds very large lines. ([#59205](https://github.com/anomalyco/opencode/pull/59205))
- Let plugins filter event subscriptions by type. ([#58864](https://github.com/anomalyco/opencode/pull/58864))
- Add configurable prompt-cache TTLs. ([#59157](https://github.com/anomalyco/opencode/pull/59157))
- Move image resizing off the main process and release idle image memory. ([#58820](https://github.com/anomalyco/opencode/pull/58820))
- Reduce repeated session-history loading during a step. ([#59091](https://github.com/anomalyco/opencode/pull/59091))
- Add an experimental API for session media and opt-in media URI support. ([#59103](https://github.com/anomalyco/opencode/pull/59103))
- Add the machine hostname to `/api/info`. ([#59090](https://github.com/anomalyco/opencode/pull/59090))
- Add experimental content-addressed blob storage for session media behind `experimental.media_blob`. ([#58656](https://github.com/anomalyco/opencode/pull/58656), [#58741](https://github.com/anomalyco/opencode/pull/58741))
- Start session history from the latest completed compaction. ([#59020](https://github.com/anomalyco/opencode/pull/59020))
- Reduce work encoding durable event payloads that are not persisted. ([#58923](https://github.com/anomalyco/opencode/pull/58923))
- Expose MCP server titles from `serverInfo`. ([#58950](https://github.com/anomalyco/opencode/pull/58950))
- Apply OpenCode Console workspace configuration as a configuration layer. ([#57703](https://github.com/anomalyco/opencode/pull/57703))
- Replace experimental evaluations with Decision APIs in the AI pkg, including OpenAI Decisions, System One, and Cloudflare Run models. ([#58758](https://github.com/anomalyco/opencode/pull/58758), [#58382](https://github.com/anomalyco/opencode/pull/58382), [#58379](https://github.com/anomalyco/opencode/pull/58379), [#58381](https://github.com/anomalyco/opencode/pull/58381))
- Convert tool schemas once to speed up tool execution. ([#58798](https://github.com/anomalyco/opencode/pull/58798), [#58848](https://github.com/anomalyco/opencode/pull/58848))
- Make Git project discovery faster while recognizing repository changes. ([#58616](https://github.com/anomalyco/opencode/pull/58616))
- Show OpenCode Console budget limits and Go usage where they block you. ([#58694](https://github.com/anomalyco/opencode/pull/58694), [#58714](https://github.com/anomalyco/opencode/pull/58714))
- Record provider-reported session costs. ([#58562](https://github.com/anomalyco/opencode/pull/58562))
- Find Git more reliably on macOS. ([#58602](https://github.com/anomalyco/opencode/pull/58602))
- Resolve model details once per prompt step. ([#58601](https://github.com/anomalyco/opencode/pull/58601))
- Let plugins manage session instruction entries for subsequent model requests. ([#56550](https://github.com/anomalyco/opencode/pull/56550))
- Add GPT-6.1 Terra and GPT-6.1 Terra Fast to Sign in with ChatGPT. ([#59359](https://github.com/anomalyco/opencode/pull/59359))

#### Bug fixes

- Wait for plugins to finish reloading before each session step and tool call. Thanks [@kernel-oops](https://github.com/kernel-oops) and [@Tarquinen](https://github.com/Tarquinen). ([#51133](https://github.com/anomalyco/opencode/pull/51133))
- Size session compaction from the provider's reported token count to preserve usable context. ([#59441](https://github.com/anomalyco/opencode/pull/59441))
- Skip unavailable models.dev API entrypoints instead of failing model catalog updates. ([#59475](https://github.com/anomalyco/opencode/pull/59475))
- Return a server error with a reference ID when the server cannot encode a response. ([#59459](https://github.com/anomalyco/opencode/pull/59459))
- Avoid warming a session while its model request is running. ([#59325](https://github.com/anomalyco/opencode/pull/59325))
- Preserve legacy MCP `codemode` settings during migration. Thanks [@tneemo](https://github.com/tneemo). ([#59126](https://github.com/anomalyco/opencode/pull/59126))
- Use the correct Vertex AI endpoints for the `eu` and `us` multi-regions. ([#59335](https://github.com/anomalyco/opencode/pull/59335))
- Accept Databricks hosts that include `http://` or `https://`. ([#59334](https://github.com/anomalyco/opencode/pull/59334))
- Keep files intact when patch edits move a file onto itself. ([#59197](https://github.com/anomalyco/opencode/pull/59197))
- Preserve literal `$0` and `$ARGUMENTS` text in custom command input. ([#59198](https://github.com/anomalyco/opencode/pull/59198))
- Close project locations concurrently during shutdown. ([#59326](https://github.com/anomalyco/opencode/pull/59326))
- Treat equivalent directory paths, including trailing slashes, as one location. ([#59327](https://github.com/anomalyco/opencode/pull/59327))
- Send valid tool schemas to Kimi for tuple, default, and keyword-like arguments. ([#59207](https://github.com/anomalyco/opencode/pull/59207))
- Expose Code Mode MCP tools directly when the `execute` permission is denied. ([#59315](https://github.com/anomalyco/opencode/pull/59315))
- Coordinate OAuth credential refreshes across locations and processes. ([#54023](https://github.com/anomalyco/opencode/pull/54023))
- List and search remote Git branches correctly without bare remote names. ([#58597](https://github.com/anomalyco/opencode/pull/58597))
- Detect AVIF, HEIC/HEIF, QuickTime, and M4A attachments correctly. ([#58480](https://github.com/anomalyco/opencode/pull/58480), [#58886](https://github.com/anomalyco/opencode/pull/58886), [#58887](https://github.com/anomalyco/opencode/pull/58887))
- Reduce memory retained by long-running tool calls and unchanged hooked model requests. ([#58448](https://github.com/anomalyco/opencode/pull/58448), [#58449](https://github.com/anomalyco/opencode/pull/58449))
- Load session diffs without reading every message, improving performance for large sessions. ([#57686](https://github.com/anomalyco/opencode/pull/57686))
- Keep active locations alive when session events use an equivalent directory path. ([#56259](https://github.com/anomalyco/opencode/pull/56259))
- Reload compatibility skills only when their own sources change. ([#59086](https://github.com/anomalyco/opencode/pull/59086))
- Avoid publishing redundant catalog updates when configuration is unchanged. ([#56267](https://github.com/anomalyco/opencode/pull/56267))
- Avoid booting idle or deleted project locations while polling session forms. ([#59083](https://github.com/anomalyco/opencode/pull/59083))
- Wait for plugins before returning agent and provider lists, preventing incomplete catalogs. ([#59082](https://github.com/anomalyco/opencode/pull/59082))
- Manage sessions and instruction entries after their project directory is deleted. ([#58997](https://github.com/anomalyco/opencode/pull/58997))
- Start fuzzy file search only on first use, reducing project startup work. ([#58959](https://github.com/anomalyco/opencode/pull/58959))
- Exit after 10 seconds when shutdown hangs and report pending work. ([#58817](https://github.com/anomalyco/opencode/pull/58817))
- Keep the models catalog fresh without redownloading it when unchanged. ([#58813](https://github.com/anomalyco/opencode/pull/58813))
- Send xAI Responses `top_k` settings and stop sending unsupported penalties. ([#58868](https://github.com/anomalyco/opencode/pull/58868))
- Honor shared parallel tool-call and service-tier settings for Groq. ([#58871](https://github.com/anomalyco/opencode/pull/58871))
- Retry throttled requests instead of misreporting them as context overflows. ([#58866](https://github.com/anomalyco/opencode/pull/58866))
- Preserve streamed text and reasoning that arrive after an OpenAI Chat finish reason. ([#58851](https://github.com/anomalyco/opencode/pull/58851))
- Classify AWS REST JSON errors consistently regardless of where the error type appears. ([#58770](https://github.com/anomalyco/opencode/pull/58770))
- Validate large base64 attachments without slowdowns or hangs. ([#58811](https://github.com/anomalyco/opencode/pull/58811))
- Retry Bedrock throttling errors as rate limits instead of context overflows. Thanks [@Irish-Joseph](https://github.com/Irish-Joseph). ([#58759](https://github.com/anomalyco/opencode/pull/58759))
- Keep working MCP tools available when a server returns malformed ones. ([#58350](https://github.com/anomalyco/opencode/pull/58350))
- Match absolute instruction-file globs across directories. Thanks [@heimoshuiyu](https://github.com/heimoshuiyu). ([#58749](https://github.com/anomalyco/opencode/pull/58749))
- Use configured provider regions in Bedrock endpoint URLs. ([#58538](https://github.com/anomalyco/opencode/pull/58538))
- Handle unknown OpenAI Chat finish reasons without failing the response. ([#58608](https://github.com/anomalyco/opencode/pull/58608))
- Avoid unnecessary Azure model updates when endpoint transforms make no change. ([#58600](https://github.com/anomalyco/opencode/pull/58600))
- Prefer JPEG for opaque browser screenshots, reducing attachment size. ([#56990](https://github.com/anomalyco/opencode/pull/56990))
- Detect generated image types from their bytes when compatible hosts omit the format. ([#58475](https://github.com/anomalyco/opencode/pull/58475))
- Keep project services alive while sessions run long tools or wait for input, with a 24-hour inactivity cap. ([#57274](https://github.com/anomalyco/opencode/pull/57274))
- Prevent unrelated configuration changes and compatibility-skill update bursts from repeatedly reloading skills. ([#56260](https://github.com/anomalyco/opencode/pull/56260))

### TUI

#### Improvements

- Reduce CPU use while animated session-tab pulses are visible. ([#59235](https://github.com/anomalyco/opencode/pull/59235))
- List OpenCode Console before OpenCode Go in the integration picker. ([#59107](https://github.com/anomalyco/opencode/pull/59107))
- Add `/usage`, model-picker, prompt, sidebar, warning, and error details for OpenCode Console usage limits. ([#58731](https://github.com/anomalyco/opencode/pull/58731))
- Make CLI service registration more reliable when concurrent processes update its files. ([#59105](https://github.com/anomalyco/opencode/pull/59105))

#### Bug fixes

- Return `opencode run --format json` server connection errors as JSON. Thanks [@andreivince](https://github.com/andreivince). ([#59366](https://github.com/anomalyco/opencode/pull/59366))
- Preserve pasted prompt text when copying it back out. ([#59209](https://github.com/anomalyco/opencode/pull/59209))
- Reliably update the background service on Windows when its files are briefly locked. ([#59105](https://github.com/anomalyco/opencode/pull/59105))
- Keep the background service state directory out of tool shells and identify processes blocking its port. ([#58815](https://github.com/anomalyco/opencode/pull/58815))
- Refresh Git branch details after switching branches. ([#58982](https://github.com/anomalyco/opencode/pull/58982))
- Keep the TUI running when a plugin slot or route renders bare text. Thanks [@anmol0b](https://github.com/anmol0b) and [@Tarquinen](https://github.com/Tarquinen). ([#58144](https://github.com/anomalyco/opencode/pull/58144))
- Accept `--server` and `--standalone` anywhere in supported CLI commands. ([#58505](https://github.com/anomalyco/opencode/pull/58505))
- Release closed and background session transcripts to prevent memory growth. ([#58434](https://github.com/anomalyco/opencode/pull/58434), [#57025](https://github.com/anomalyco/opencode/pull/57025))
- Connect remote access tunnels through HTTP proxies. ([#58464](https://github.com/anomalyco/opencode/pull/58464))
- Keep development builds on a separate server, database, and port from released builds. ([#58331](https://github.com/anomalyco/opencode/pull/58331))

### Desktop

#### Improvements

- Manage desktop plugins from Settings › Extensions › Plugins. ([#59489](https://github.com/anomalyco/opencode/pull/59489))
- Add a persistent desktop zoom setting. ([#59277](https://github.com/anomalyco/opencode/pull/59277))
- Capture heap snapshots in desktop debug builds on `SIGUSR2` when explicitly enabled. ([#58317](https://github.com/anomalyco/opencode/pull/58317))
- Show the open session title in the browser tab. ([#59131](https://github.com/anomalyco/opencode/pull/59131))
- Show todowrite tasks above the composer. ([#59092](https://github.com/anomalyco/opencode/pull/59092))
- Load session history once when returning to a session tab. ([#59166](https://github.com/anomalyco/opencode/pull/59166))
- Answer questions with number keys and show multi-select choices as checkboxes. ([#58595](https://github.com/anomalyco/opencode/pull/58595))
- Add an always-available Add project action to the location picker. ([#57962](https://github.com/anomalyco/opencode/pull/57962))
- Let you rewind or fork from any message. ([#58865](https://github.com/anomalyco/opencode/pull/58865))
- Let you edit line comments and copy shell output. ([#58970](https://github.com/anomalyco/opencode/pull/58970), [#58974](https://github.com/anomalyco/opencode/pull/58974))
- Render Mermaid diagrams in messages much faster, sized to fit the column. ([#57483](https://github.com/anomalyco/opencode/pull/57483), [#57004](https://github.com/anomalyco/opencode/pull/57004))
- Add opt-in memory logging and remote debugging for desktop debug builds. ([#58315](https://github.com/anomalyco/opencode/pull/58315))
- Show web sources for a turn behind the experimental Sources setting. ([#58307](https://github.com/anomalyco/opencode/pull/58307))
- Jump from a completed shell notification to its shell output. ([#58663](https://github.com/anomalyco/opencode/pull/58663))
- Keep the composer usable while the voice-call panel floats. ([#58587](https://github.com/anomalyco/opencode/pull/58587))
- Use the Soft Radar activity spinner by default and provide experimental variations. ([#58010](https://github.com/anomalyco/opencode/pull/58010), [#57903](https://github.com/anomalyco/opencode/pull/57903))
- Add an experimental new model picker. ([#58413](https://github.com/anomalyco/opencode/pull/58413))
- Add experimental Console voice calls in Desktop beta. ([#58249](https://github.com/anomalyco/opencode/pull/58249))
- Add a timeline width setting. ([#58308](https://github.com/anomalyco/opencode/pull/58308))
- Improve command, session, and model search lists with sticky sections. ([#58222](https://github.com/anomalyco/opencode/pull/58222))
- Add search to recently closed sessions. ([#55721](https://github.com/anomalyco/opencode/pull/55721))
- Open extension configuration and skills in side tabs. ([#58023](https://github.com/anomalyco/opencode/pull/58023))
- Open session extension lists on hover and follow keyboard navigation. ([#58021](https://github.com/anomalyco/opencode/pull/58021))
- Add video previews with zoom controls. ([#57924](https://github.com/anomalyco/opencode/pull/57924))
- Add generated project avatars and an experimental avatar-style switcher. ([#57871](https://github.com/anomalyco/opencode/pull/57871), [#57930](https://github.com/anomalyco/opencode/pull/57930))
- Add recently closed side tabs to the new-tab view. ([#57863](https://github.com/anomalyco/opencode/pull/57863))
- Add a searchable prompt history picker. ([#57716](https://github.com/anomalyco/opencode/pull/57716))
- Find settings from the command palette. ([#57651](https://github.com/anomalyco/opencode/pull/57651))
- Group queued and steered messages, and group consecutive user messages under one metadata line. ([#57561](https://github.com/anomalyco/opencode/pull/57561), [#57552](https://github.com/anomalyco/opencode/pull/57552))
- Improve file-tree and folder-picker performance. ([#57573](https://github.com/anomalyco/opencode/pull/57573), [#57557](https://github.com/anomalyco/opencode/pull/57557))
- Keep branch search results visible while new results load. ([#57531](https://github.com/anomalyco/opencode/pull/57531))
- Add a session-details menu to the session header. ([#57528](https://github.com/anomalyco/opencode/pull/57528))
- Show a subagent's model, status, and elapsed time in its composer area. ([#57473](https://github.com/anomalyco/opencode/pull/57473))
- Let you delete sessions from tab menus and rena
Weekly digest: every breaking change, retirement and price change across 23 coding agents, one email.

Form not loading? Subscribe here.