norandom · Oct 22, 2026 · Oct 29, 2026 · Oct 29, 2026 · Nov 5, 2026 · Nov 5, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,62 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+Review fixes for the OpenCode 2.x port; request shapes verified against a live OpenCode 2.2.5 server.
+
+- Select agents through the session agent surface: new sessions take `agent` at creation, existing sessions switch with `POST /api/session/{id}/agent`. The 2.x prompt endpoint silently drops an `agent` field.
+- Queue prompts with `delivery: "queue"` so a prompt dispatched while a turn runs executes as its own turn; the server's default `steer` merges it into the running turn.
+- Page session messages with the opaque `cursor` while observing, so a job still finishes when its turn spans more than the server's page size.
+- End the observed turn at its idle marker instead of the next user message. A steered follow-up no longer truncates the turn, and the merged turn's idle marker completes the original job.
+- `opencode_ask` and `opencode_reply` no longer present a partial answer as final when the wait deadline expires: the result is flagged `timedOut`, marked as an error, and carries a `TIMEOUT` note with the session to resume. Failures of the wait endpoint itself now surface instead of being swallowed.
+- Read pending job inputs from the per-session `GET /api/session/{id}/form` and `GET /api/session/{id}/permission` routes instead of the location-scoped lists, which only cover the server's current directory.
+- Windows smoke runs: `scripts/mcp-smoke-test.mjs` silently exited 0 without running anything when the direct-invocation path check mismatched (drive junctions, substituted or differently-spelled paths); it now compares real paths, so the checks actually execute. Disposable-fixture cleanup no longer crashes a passing run on `EBUSY`: deletion retries through transient handle lag, and when a long-lived OpenCode server still holds a project-watcher handle on the fixture directory, the script warns with the path and keeps the exit code tied to the smoke results.
+
+## [4.0.0] - 2026-10-22
+
+### Breaking changes
+
+- Require an OpenCode 2.x server (tested against 2.1.2). All requests use the `/api/*` server API through the `@opencode-ai/sdk` v2 client (`^1.19.3`, `./v2/client`). An OpenCode 1.x server is detected at startup and rejected with an upgrade message; stay on 3.x to keep using OpenCode 1.x.
+- OpenCode 2.x always enforces HTTP Basic authentication. For an external server, `OPENCODE_SERVER_PASSWORD` must match the server's password (username `opencode` by default); a server started without one prints a generated password at startup. A rejected password now produces an explicit credentials error.
+- Remove prompt-level structured output. OpenCode 2.x dropped response formats, so the `format` parameter is gone from `opencode_ask`, `opencode_reply`, `opencode_run`, `opencode_fire`, `opencode_provider_test`, `opencode_message_send`, and `opencode_message_send_async`. Ask for machine-readable output in the prompt text instead.
+- `opencode_question_reply` now answers an OpenCode 2.x form: it takes `answer`, an object keyed by form field key, instead of `answers`. It and `opencode_question_reject` accept an optional `sessionId`, looked up from the pending form list when omitted.
+- Tool parameter changes following the 2.x API:
+  - `opencode_message_send` drops `noReply` and `system`, and adds `timeoutMs`; `opencode_ask` drops `system`.
+  - `opencode_command_execute` drops `agent`, `providerID`, `modelID`, and `variant`; `opencode_shell_execute` drops `agent`, `providerID`, and `modelID`.
+  - `opencode_session_summarize` compacts a session and no longer takes a provider/model/variant.
+  - `opencode_session_revert` replaces `partID` with `files`; `opencode_session_unrevert` discards staged revert changes.
+  - `opencode_find_text` matches file and directory paths; OpenCode 2.x has no line-level text search. `opencode_find_file` drops `searchDirectory`.
+  - `opencode_auth_set` drops `type` and adds an optional `label`. `opencode_provider_oauth_authorize` takes an optional `methodID` instead of `method`/`inputs`; `opencode_provider_oauth_callback` takes `attemptID` and an optional `code` instead of `callbackData`.
+  - `opencode_config_update` is limited to the fields OpenCode 2.x can patch (currently `shell`).
+
+### Changed
+
+- Select models per session. New sessions are created with the chosen model; passing a model or `variant` for an existing session switches its model for later turns.
+- Submit prompts to OpenCode's asynchronous session inbox and correlate completion with the idle marker that closes the submitted turn. Interrupted and failed turns map to `cancelled` and `failed`.
+- Questions are backed by OpenCode 2.x forms. Job input still takes one answer array per field in field order and maps it to field keys, option values, booleans, and numbers.
+- Cancellation (`opencode_job_cancel`, `opencode_session_abort`) uses OpenCode's session interrupt. `opencode_session_abort` adds an optional `resume` flag.
+- `opencode_session_create` accepts optional `agent`, `providerID`, and `modelID`; `opencode_session_permission` accepts an optional `message`.
+- Health checks use `GET /api/info`. Events come from the single `/api/event` stream, scoped by directory for project polling and unscoped for global polling.
+- `OPENCODE_AUTO_SERVE=true` now spawns `opencode serve` directly with a randomly generated private password instead of using the SDK launcher.
+- The 3.1.0 OpenChamber sign-in and `OPENCODE_SERVER_TOKEN` bearer auth carry over and apply to API requests, the `/api/event` stream and the `/api/info` probe. They need OpenChamber 2.0 or newer, which fronts OpenCode 2.x and passes `/api/*` through unchanged.
+
+### Removed
+
+- Tools without an OpenCode 2.x equivalent: `opencode_find_symbol`, `opencode_formatter_status`, `opencode_instance_dispose`, `opencode_log`, `opencode_lsp_status`, `opencode_session_init`, `opencode_session_share`, `opencode_session_todo`, `opencode_session_unshare`, `opencode_tool_ids`, and `opencode_tool_list`.
+- All nine TUI control tools (`opencode_tui_*`).
+- The OpenCode 1.18.31 response-format history-serialization workaround and the `StructuredOutput` permission guidance.
+- Tool count: 67 in the full profile (down from 87); the essential profile still exposes 25.
+
+### Migration notes
+
+- Upgrade OpenCode to 2.x and restart its server before upgrading the MCP.
+- Set `OPENCODE_SERVER_PASSWORD` in the MCP client environment to the server's password, or use `OPENCODE_AUTO_SERVE=true` for a local child server.
+- Remove `format` arguments from prompt calls and request the desired output shape in the prompt. Replace calls to removed tools; session todos are no longer exposed.
+- Update direct `opencode_question_reply` callers to send `answer: {"<field-key>": value}`. Use `opencode_question_list` to inspect field keys. `opencode_job_input` responses are unchanged.
+- Passing a model on a follow-up now changes the session's model for later turns, not only the current prompt.
+- OpenChamber users: upgrade to OpenChamber 2.0 or newer and drop the `/api` suffix from `OPENCODE_BASE_URL`.
+
 ## [3.1.0] - 2026-10-29
 
 This release supports OpenCode 1.x only and was tested with OpenCode 1.19.3. OpenCode 2.x servers are not supported in 3.x; support is planned for 4.0.

diff --git a/README.md b/README.md
@@ -6,24 +6,24 @@
 
 **Delegate coding work to OpenCode from your MCP client.**
 
-opencode-mcp connects Claude, Cursor, VS Code, and other MCP clients to OpenCode's headless API. Ask questions, implement features, monitor background work, respond to questions and permissions, and review changes across projects.
+opencode-mcp connects Claude, Cursor, VS Code, and other MCP clients to OpenCode's headless API (OpenCode 2.x). Ask questions, implement features, monitor background work, respond to questions and permissions, and review changes across projects.
 
-> Version 3.x requires **Node.js 22 or newer** and works with **OpenCode 1.x** (tested with 1.18.31 and 1.19.3). Support for OpenCode 2.x is planned for 4.0. Upgrading from 2.x? See the [migration notes](CHANGELOG.md#300---2026-09-16).
+> Version 4.x requires an **OpenCode 2.x server** (tested with 2.1.2 and 2.2.0) and **Node.js 22 or newer**. OpenCode 1.x servers are detected and rejected; OpenCode 1.x users stay on 3.x. Upgrading from 3.x? See the [migration notes](CHANGELOG.md#400---2026-10-22).
 
 ## Quick Start
 
-Install [OpenCode](https://opencode.ai/docs/) and start its server from your project:
+Install [OpenCode](https://opencode.ai/docs/) 2.x and start its server from your project:
 
 ```bash
-opencode serve --hostname 127.0.0.1 --port 4096
+OPENCODE_SERVER_PASSWORD=<choose-a-password> opencode serve --hostname 127.0.0.1 --port 4096
 ```
 
-If you use the TUI, start it with `opencode --port 4096` and share that server. Set `OPENCODE_BASE_URL` for another endpoint.
+OpenCode 2.x always requires HTTP Basic authentication. Give the MCP the same password through `OPENCODE_SERVER_PASSWORD` (username `opencode`). If you start the server without a password, OpenCode prints a generated one at startup. If you use the TUI, start it with `opencode --port 4096` and share that server. Set `OPENCODE_BASE_URL` for another endpoint.
 
 For Claude Code:
 
 ```bash
-claude mcp add opencode -- npx -y opencode-mcp
+claude mcp add opencode --env OPENCODE_SERVER_PASSWORD=<server-password> -- npx -y opencode-mcp
 ```
 
 For clients using an `mcpServers` configuration:
@@ -33,13 +33,14 @@ For clients using an `mcpServers` configuration:
   "mcpServers": {
     "opencode": {
       "command": "npx",
-      "args": ["-y", "opencode-mcp"]
+      "args": ["-y", "opencode-mcp"],
+      "env": { "OPENCODE_SERVER_PASSWORD": "<server-password>" }
     }
   }
 }
 ```
 
-Restart the client and call `opencode_setup`. Choose a provider from its configured providers, then use `opencode_provider_models` to select a model. Set `OPENCODE_DEFAULT_PROVIDER` and `OPENCODE_DEFAULT_MODEL` together or pass the selected IDs in each prompt call.
+Restart the client and call `opencode_setup`. Choose a provider from its configured providers, then use `opencode_provider_models` to select a model. Set `OPENCODE_DEFAULT_PROVIDER` and `OPENCODE_DEFAULT_MODEL` together or pass the selected IDs in prompt calls. OpenCode 2.x selects models per session: passing a model for an existing session switches that session's model for later turns.
 
 [Client-specific configuration](docs/configuration.md) includes VS Code, Windsurf, Continue, Zed, and Amazon Q. To test unreleased changes, [build from source](CONTRIBUTING.md) and configure your client to run `node` with the absolute path to `dist/index.js`.
 
@@ -69,7 +70,7 @@ Async results distinguish `accepted`, `running`, `input_required`, `completed`,
 
 Modern clients can use the MCP Tasks extension for `opencode_run`. Clients without that extension use ordinary tools, including `opencode_fire` and `opencode_check`. Task status is retrieved by polling; this package does not promise to wake an idle assistant with completion notifications.
 
-Tools retain readable text and provide structured results for clients that consume them. Prompt tools accept optional model variants and OpenCode structured-output formats. See the [generated tools reference](docs/tools.md) and [examples](docs/examples.md).
+Tools retain readable text and provide structured results for clients that consume them. Prompt tools accept optional model variants; OpenCode 2.x has no prompt-level structured-output format, so ask for machine-readable output in the prompt text. See the [generated tools reference](docs/tools.md) and [examples](docs/examples.md).
 
 ## Multi-Project Use
 
@@ -81,16 +82,16 @@ Independent sessions do not isolate filesystem changes. Use separate project dir
 
 ## Configuration
 
-All settings are optional; an OpenCode server must already be running by default.
+An OpenCode 2.x server must already be running by default, and its password must be supplied through `OPENCODE_SERVER_PASSWORD` unless the MCP starts the server itself.
 
 | Variable | Purpose |
 |---|---|
 | `OPENCODE_BASE_URL` | Server endpoint; defaults to `http://127.0.0.1:4096` |
-| `OPENCODE_SERVER_USERNAME`, `OPENCODE_SERVER_PASSWORD` | Optional server HTTP authentication |
+| `OPENCODE_SERVER_USERNAME`, `OPENCODE_SERVER_PASSWORD` | Server HTTP Basic authentication; username defaults to `opencode`, password must match the server's |
 | `OPENCODE_SERVER_TOKEN` | Optional bearer token, e.g. an OpenChamber client token |
 | `OPENCODE_OPENCHAMBER_PASSWORD`, `OPENCODE_OPENCHAMBER_URL` | Sign in to an [OpenChamber](https://github.com/openchamber/openchamber)-fronted server |
 | `OPENCODE_OPENCHAMBER_CLIENT_ID` | Overrides the per-process OpenChamber client identifier; see [configuration](docs/configuration.md#openchamber) |
-| `OPENCODE_AUTO_SERVE` | Set to `true` to opt in to launching a local server |
+| `OPENCODE_AUTO_SERVE` | Set to `true` to opt in to launching a local server with a generated private password |
 | `OPENCODE_DEFAULT_PROVIDER`, `OPENCODE_DEFAULT_MODEL` | Default prompt provider/model pair |
 | `OPENCODE_TOOL_PROFILE` | `full` (default) or a smaller `essential` tool set |
 | `OPENCODE_TASK_STORE` | Override the local directory for persisted job records |