Skip to content
UHPUHPDeveloper Guide
Independent developer guide. Not affiliated with HarnessRouter or the official UHP project.

OpenCode with UHP or ACP: choose an integration

OpenCode can connect to clients through its native ACP surface or run behind HarnessRouter's UHP adapter. These interfaces address different ownership and lifecycle needs.

Page reviewed 4 Oct 2026 Source and review policy

Current guidance and dated source history

Separate restored state from a new conversation

Section titled “Separate restored state from a new conversation”

An OpenCode integration should decide what to do when it cannot recover native state before accepting a follow-up request. A successful first answer does not exercise that path. The current upstream project distinguishes Build and Plan agents; Plan constrains edits and asks before Bash. Choose the native agent/policy deliberately rather than assuming a UHP request’s text changes execution permissions.

Continuation caseRequired application behavior
Native state present and owned by the expected sessionContinue and retain the external/native mapping
State missing after a worker restartSurface a recovery failure or explicitly create a new session
Tool policy changes between turnsRecheck policy application and record the new configuration
Caller loses the streamRead the stored Response before deciding whether to retry

Use a disposable fixture to distinguish a real restoration from a coincidental correct answer: first write a unique value, restart only the worker through your documented process, then request that value through the same session. Capture native state ownership and artifact evidence. This is a proposed acceptance experiment, not a reported result.

The newest OpenCode binary and the adapter’s moving latest install selection cannot certify this experiment. Keep session recovery and routing identity in the implementation design: the same human-visible title is not the same durable session, and a reconnect is not permission to rerun an uncertain turn.

Choose the outer interface

Section titled “Choose the outer interface”
You are buildingStart withVerify
An editor or interactive ACP clientOpenCode’s ACP documentationThe client’s and agent’s negotiated capabilities
A product that can switch complete harnessesHarnessRouter’s UHP APIInstalled OpenCode version, provider route and adapter semantics
A direct OpenCode automationOpenCode’s own documented interfacesIts own session, event and permission contract

Native ACP support is not native UHP support. HarnessRouter first released its OpenCode backend in v0.10.0; that remains adapter evidence.

Current release and installation behavior

Section titled “Current release and installation behavior”

The latest upstream stable release observed on 4 October 2026 is v1.18.34. HarnessRouter v0.29.0 allows HR_OPENCODE_VERSION and defaults it to latest in the entrypoint. That is a moving installation selection, not a fixed tested version.

Record the actual installed executable version in any compatibility result. For reproducible deployment, inspect the version-override behavior and pin deliberately after checking the required provider/tool flow. Do not relabel old measured turns as validation of a newly downloaded binary.

Check continuation before relying on it

Section titled “Check continuation before relying on it”

A useful acceptance case writes a small artifact, continues the same session and reads that artifact back. Also exercise the failure path when native session state is absent: a clear continuation failure is preferable to silently starting unrelated work. The historical notes below describe specific released recovery and checkpoint fixes; they are not evidence of a fresh deployment test.

Continue with UHP vs ACP and lifecycle semantics to define the behavior your client expects.

Historical source notes — baseline reviewed 19 Sep 2026

The following evidence preserves the earlier review and its links. “Current”, “stable” and “main” inside this section refer to that historical cutoff; they are not new release or compatibility claims. Use the guidance above for the current scope.

Status first

Section titled “Status first”

OpenCode is a released HarnessRouter backend. Pull request #29, “feat: OpenCode backend,” merged on 26 August 2026 at commit f0d5661. HarnessRouter’s annotated v0.10.0 tag points directly to that commit and names “OpenCode backend; collection cursor; restart-orphan recovery”; GitHub Release v0.10.0 was published on 28 August 2026. The latest HarnessRouter release observed is v0.19.0 / ccf4af66, published 19 September 2026 at 06:19:09 UTC. OpenCode’s checkpoint-ownership evidence landed in PR #194 at faba1925, first released in v0.17.3, and remains in the current stable line. Stable v0.19.0 has thirteen released backends after Aider became backend aider. Checked HarnessRouter main is later 387ad841551af02001ed6e9c85a25232f0ad9385 after post-release PR #216 corrected OpenCode reasoning/output usage accounting and PR #214 aligned console-proxy timeouts with the declared route lifetime. Neither post-release change is part of v0.19.0, and neither establishes a new OpenCode-specific UHP conformance run.

The upstream OpenCode project is the MIT-licensed open-source coding agent at anomalyco/opencode. HarnessRouter’s integration was developed against the released OpenCode v1.18.23 configuration contract during the pre-merge fixes. Upstream OpenCode has since advanced to stable v1.18.31, published 14 September 2026 at 17:47:30 UTC. v1.18.26 hardens Claude 5 stale-thinking-block recovery after prompt/tool changes, Bedrock GPT-5.6 reasoning/replay behavior, tool-call timing, and Azure CLI sign-in. v1.18.27 then raises default provider-header and streamed-chunk timeouts to five minutes, permits disabling the streamed-chunk timeout, constrains Anthropic thinking-block binding to Claude 5.1+, lets configuration opt out of that binding, and avoids unhandled errors when canceling timed-out SSE reads. v1.18.28 sends the OpenCode session ID as GitHub Copilot’s interaction header to improve request tracking across a session and corrects the desktop client ID used during OpenCode-account device authentication. v1.18.29 fixes Codex OAuth model filtering so integer-version identifiers such as gpt-6 are recognized instead of requiring a decimal version; the release specifically records the resulting fix for gpt-6-astra not appearing for OpenAI subscription users. v1.18.30 adds the Astra system prompt for GPT-6 models, preserves Bedrock DeepSeek model identifiers including ARN-based IDs, updates the Azure and OpenAI provider SDKs for compatibility fixes, and adds reasoning-effort variants for supported GitLab GPT and Claude models. v1.18.31 then promotes the ACP session-restoration and reasoning-boundary fix described below into the stable release line and also surfaces remote-auth startup errors in the TUI instead of hiding them during startup.

Those v1.18.26–v1.18.31 changes are upstream OpenCode behavior, not a UHP change and not new HarnessRouter conformance evidence. This guide has not independently established that HarnessRouter’s OpenCode backend was revalidated specifically against every newer upstream release; the backend’s published pre-merge integration evidence remains the v1.18.23-era work described below. PR #216 is separate HarnessRouter evidence measured against OpenCode 1.18.31 for usage normalization, not a blanket revalidation of the adapter.

HarnessRouter v0.12.1 also changes implementation-wide routing: PR #52 replaces handwritten backend inference with catalogue-derived routing after a live Qwen misrouting defect and records the GLM-5.3-family live matrix. That hardening includes OpenCode in the expanded eight-backend release line, but it does not alter OpenCode’s native protocol surface or constitute an OpenCode-specific UHP conformance run. Current stable v0.19.0 has 13 released backends after Gemini CLI, Oh My Pi, Goose, Kimi and Aider later joined the set. PR #71, released in v0.13.5, wires Google AI Studio to OpenCode through Gemini’s OpenAI-compatible Chat Completions endpoint; v0.13.8 repairs Google provider-catalog/saveability and shared Google request fallback behavior.

Post-v0.19.0 current main: OpenCode reasoning is part of generated output usage

Section titled “Post-v0.19.0 current main: OpenCode reasoning is part of generated output usage”

HarnessRouter PR #216, merged 19 September 2026 as 83b3826754911afcd40707a2137a48106ea96245, fixes a cross-backend usage-accounting mismatch. OpenCode’s Session.getUsage reports visible generated text as tokens.output after subtracting reasoning, while carrying the reasoning amount separately as tokens.reasoning. HarnessRouter’s _opencode_usage_add had read only tokens.output, so an OpenCode turn could appear materially cheaper than a backend whose completion-token field already includes reasoning.

The PR’s measured 22-request SpreadsheetBench example records 7,445 visible output tokens + 10,582 reasoning tokens = 18,027 generated tokens in OpenCode’s own stored message rows, while the pre-fix HarnessRouter turn record reported only 7,445. The fix adds valid reasoning tokens back into output_tokens; OpenCode input/cache accounting remains unchanged. On an Anthropic connection where OpenCode reports no separate reasoning amount, behavior is unchanged. The PR reports 379 runner tests passing, and its patched examples record 3,557 + 7,203 = 10,760 and 4,296 + 6,960 = 11,256, matching OpenCode’s own sums.

This is HarnessRouter current-main accounting behavior, not an upstream OpenCode token-definition change, not a UHP token-accounting requirement and not yet a newer stable HarnessRouter release. It matters operationally because normalized usage can drive cost attribution, support-matrix comparisons and billing.

v0.17.3: checkpoint ownership removes recursive OpenCode state growth

Section titled “v0.17.3: checkpoint ownership removes recursive OpenCode state growth”

HarnessRouter PR #194, merged 17 September 2026 as faba1925d02c9b9fcff6ac2118ee18238032659b, fixes a persistence-layer feedback loop specific to the way the reference runner hosted OpenCode. HarnessRouter’s workspace Git repository was committing .harness/home, while OpenCode’s own snapshot Git repository used that workspace as its work tree. The two repositories could therefore capture each other’s state on successive turns. The fix was first released in HarnessRouter v0.17.3 and remains inherited by stable v0.19.0 and current main.

Issue #193 measured the failure after roughly 20 small turns: a checkpoint reached about 1.4 GB compressed / 1.6 GB of members and roughly 140,000 files for about 220 KB of agent output. .harness/home accounted for 887 MB and the workspace .git/objects for 722 MB; on local backing the gateway then buffered the large tar and the host reached a global OOM.

PR #194 separates the two persistence domains. New workspaces ignore .harness/home/ in the workspace Git repository while the directory still travels in the ordinary checkpoint tar, so native session state remains available for resume. Generated OpenCode configuration now sets "snapshot": false because HarnessRouter’s turn checkpoint, rather than OpenCode’s interactive undo repository, is the rollback boundary in this one-shot-per-turn runner. Existing pre-fix sessions are migrated rather than merely ignored: _git_ensure untracks the home without deleting it, excludes the obsolete OpenCode snapshot store from later checkpoints, rewrites reachable workspace history down to the produced-file cursor/HEAD trees without the home, expires reflogs and prunes the old blobs. The PR reports one real-image migration shrinking workspace .git from 25 MB to 304 KB and its checkpoint from 28.2 MB to 3.0 MB while the conversation resumed; a ten-turn simulated case reduced an 84 MB checkpoint to 7 MB.

The merge also incorporates the warm-resume correction developed as PR #195: a cached workspace marker now vouches for a warm workspace only when the matching workspace still contains .git, and DELETE /workspace clears the marker. That prevents a stale marker from causing the gateway to skip restore and start a continuation in an empty workspace.

This is HarnessRouter runtime behavior first released in v0.17.3 and inherited by v0.19.0, not OpenCode v1.18.31 behavior, not a UHP protocol revision and not a new conformance measurement. The durable architectural rule is that checkpoint transport state and produced-file Git history need separate ownership; two nested persistence systems must not recursively persist each other, and a warm-state marker must prove the state it claims still exists.

v0.15.7 makes a lost OpenCode continuation explicit

Section titled “v0.15.7 makes a lost OpenCode continuation explicit”

HarnessRouter v0.15.7 releases PR #139, which tightens a runtime/session-verification boundary for OpenCode and Claude Code. A request may carry a prior OpenCode native session id while the restored workspace no longer contains that session. Before this release, the OpenCode builder could omit --session; the CLI would then begin a fresh conversation and could still return a fluent completed answer.

HarnessRouter now checks whether a requested OpenCode session id is actually present in the built command. If not, it emits system/resume_lost and the gateway prefixes the reply with a note that the earlier conversation could not be restored and the reply continues as a new session without that context. The support-matrix recall judge treats that note as failed recall, rather than accepting a fresh-session completion as successful continuity. PR #139 records four motivating hosted restored OpenCode sessions whose recalls behaved as fresh conversations before the fix.

This is HarnessRouter adapter/runtime behavior. It does not change upstream OpenCode’s ACP or session contract, does not add a UHP conformance check, and does not establish native OpenCode UHP adoption.

v0.13.9 repairs OpenCode’s direct Anthropic path

Section titled “v0.13.9 repairs OpenCode’s direct Anthropic path”

HarnessRouter v0.13.9 releases PR #85, a support-matrix-driven correction specific to OpenCode’s direct Anthropic route. The built-in Anthropic catalog base previously omitted /v1; OpenCode’s Anthropic SDK appended /messages, producing an unversioned https://api.anthropic.com/messages route instead of /v1/messages. The support matrix recorded direct-Anthropic OpenCode failing the first turn on both v0.13.7 and v0.13.8 while Pi and Hermes passed with the same key.

The released runner now appends /v1 for the built-in Anthropic catalogue base and the catalogue default itself carries /v1. An explicit custom endpoint remains exact rather than being rewritten. This is HarnessRouter provider-adapter compatibility, not a change to upstream OpenCode, UHP, ACP, the backend count or native UHP adoption. v0.13.10 then releases the related loopback-relay correction for relay-borne Cline/Qwen traffic; it does not alter OpenCode’s already-released PR #85 path. Historical post-v0.13.10 PR #87 changes support-matrix validation tooling only.

OpenCode also implements ACP natively

Section titled “OpenCode also implements ACP natively”

Separately from UHP, upstream OpenCode itself publishes a native Agent Client Protocol (ACP) interface. The tagged v1.18.31 documentation tells ACP-compatible editors and IDEs to run opencode acp; that command starts OpenCode as an ACP-compatible subprocess communicating over JSON-RPC via stdio. The same tagged release retains the native ACP command. The current official ACP registry manifest, however, still pins OpenCode 1.18.30.

The latest official protocol matrix was generated on 14 September 2026 at 10:43:07 UTC and directly probes that same registry-pinned OpenCode 1.18.30 binary. Initialization succeeds with terminal authentication and advertises loadSession, session/list, session/fork and session/resume. That direct-probe evidence remains version-bounded to 1.18.30; the publication of v1.18.31 must not be treated as an automatic matrix revalidation.

v1.18.31: ACP session-option and reasoning-boundary fidelity is now stable

Section titled “v1.18.31: ACP session-option and reasoning-boundary fidelity is now stable”

OpenCode PR #48225, merged into the project’s dev branch on 11 September 2026 at 95daf90670b7c039c436c85537da5fbfe2205b41, fixes two ACP host-fidelity defects. OpenCode v1.18.31 now releases that work; the release notes explicitly describe restoring ACP session model, effort, mode, and reasoning chunk boundaries when loading, resuming or forking sessions.

First, streamed reasoning now uses the reasoning part id as the ACP messageId, both for live deltas and transcript replay, instead of grouping every reasoning part under the parent assistant-message id. That preserves boundaries between separate reasoning parts instead of allowing adjacent thought chunks to be concatenated without a separator by an ACP host.

Second, ACP session load/resume/fork restoration reconstructs the effective model, variant/reasoning-effort selection and agent/mode from the backing session plus retained message state before publishing configuration options. The effort selector also preserves the explicit default variant as a selectable/current value. The PR’s verification describes running OpenCode ACP inside Zed with GPT-5.6 Sol at high reasoning effort, closing Zed and reopening the session with the same effort restored.

This is now stable OpenCode v1.18.31 behavior, but the official ACP registry and the 14 September protocol matrix still pin/probe 1.18.30. The fix improves OpenCode’s implementation of ACP session/configuration and streaming semantics; it does not revise the ACP specification, change UHP 2026-09-12, establish native OpenCode UHP adoption, or show that HarnessRouter’s UHP→OpenCode adapter traverses OpenCode’s ACP server.

This is stronger than an adapter-only ecosystem listing: ACP support lives in OpenCode’s own upstream code and documentation. It is still a different protocol boundary from HarnessRouter’s UHP adapter. An editor can talk ACP directly to OpenCode, while a UHP client talks to HarnessRouter and HarnessRouter launches and adapts OpenCode underneath. No primary source reviewed establishes that HarnessRouter’s UHP→OpenCode path uses OpenCode’s ACP server, and native OpenCode ACP support does not establish native OpenCode UHP support.

What HarnessRouter added

Section titled “What HarnessRouter added”

The backend gave HarnessRouter a sixth harness runtime alongside Claude Code, Codex, Hermes, Pi and DeepSeek Harness. It first shipped in v0.10.0; current stable v0.19.0 contains 13 released backends after Qwen Code, Cline, Gemini CLI, Oh My Pi, Goose, Kimi and Aider joined the set.

The runner integration uses OpenCode’s non-interactive JSON event surface and translates those events into HarnessRouter’s existing task/session pipeline. During implementation, HarnessRouter added or corrected several backend-specific details:

  • Structured execution: OpenCode runs through its JSON-formatted CLI stream rather than terminal scraping.
  • Session continuation: the adapter carries OpenCode session identity so UHP continuation through previous_response_id can remain on the same OpenCode conversation; v0.15.7 now reports explicitly when that native session could not actually be resumed.
  • MCP and skills: HarnessRouter materializes configured MCP servers and skill paths into OpenCode’s released configuration shape. OpenCode receives harness instructions through AGENTS.md, which is the instruction filename its loader reads.
  • Tool enforcement: HarnessRouter maps disabled tools into OpenCode’s native permission model, using hard deny semantics rather than relying only on model instructions.
  • Plugin isolation: the runner uses OpenCode’s pure-mode path so workspace plugin configuration cannot silently expand the harness execution surface.
  • Model/provider routing: the gateway exposes OpenCode across the multi-family model catalogue supported by HarnessRouter’s serving paths rather than pinning the backend to a single model family.
  • Checkpoint ownership since v0.17.3: PR #194 keeps redirected CLI home/session state in the checkpoint tar but outside the workspace Git history and disables redundant OpenCode snapshots, with migration for existing recursive histories. That behavior is inherited by v0.19.0.
  • Current-main usage normalization: PR #216 adds separately reported reasoning to output_tokens, keeping generated-output accounting comparable with backends whose completion count already includes reasoning.

These are HarnessRouter implementation choices. UHP itself does not require an OpenCode CLI, OpenCode configuration file, AGENTS.md, a specific permission syntax, a specific checkpoint implementation, any particular model catalogue or HarnessRouter’s usage-normalization convention.

Evidence of a working turn

Section titled “Evidence of a working turn”

Before the backend merge, HarnessRouter recorded an end-to-end correction for two failures that had prevented reliable OpenCode execution: the child process inherited a stale PWD, and built-in harness ids could fall through to model-name-based backend guessing. After fixing both, the upstream commit records a live console/BFF check where:

  • an OpenCode turn completed on gpt-5.4; and
  • a second turn completed through previous_response_id, preserving session continuity.

The same commit reports the repository test suite passing at that point. PR #139 later adds the complementary failure rule: if the native OpenCode session id cannot actually be put on the built command, HarnessRouter reports lost continuity instead of treating the fresh session as a successful resume. PR #216 adds later current-main evidence specifically for usage-accounting parity, not a new UHP conformance run.

Released state

Section titled “Released state”
QuestionVerified answer
Is OpenCode in HarnessRouter current releases?Yes. It first shipped in v0.10.0; latest stable v0.19.0 includes it among 13 released backends.
What is the latest stable upstream OpenCode release observed?v1.18.31, published 14 Sep 2026. It releases the ACP session-restoration and reasoning-boundary fix previously tracked on dev.
Does OpenCode itself implement another interoperability protocol?Yes — ACP. Upstream v1.18.31 documents and ships opencode acp; the official ACP registry still pins OpenCode 1.18.30, and the 14 Sep protocol matrix directly probes that exact 1.18.30 version successfully with loadSession, session/list, session/fork and session/resume.
What changed in HarnessRouter v0.17.3 for the OpenCode runner?PR #194 separates CLI-home checkpoint state from workspace Git history, disables redundant OpenCode snapshots and repairs stale warm-workspace markers. Later stable releases inherit that fix.
What changed after v0.19.0 on HarnessRouter current main?PR #216 adds OpenCode’s separate reasoning count into output_tokens; PR #214 separately fixes the console’s long-turn proxy timeout. Neither is part of v0.19.0 yet.
What is HarnessRouter current main?387ad841551af02001ed6e9c85a25232f0ad9385, after PR #216 and PR #214; backend count remains 13.
What is the current UHP protocol line?2026-09-12, with conformance package 2026.9.12 and current source containing 75 checks.
Is there OpenCode-specific complete current conformance evidence published?Not established by the sources reviewed for this page.
Does this prove OpenCode adopted UHP natively?No. It proves HarnessRouter integration.

Why this matters

Section titled “Why this matters”

OpenCode broadens the reference implementation’s harness-substitution surface while keeping the external UHP client contract unchanged. It is also a useful example of why UHP and backend integration must be separated conceptually: clients keep speaking the same UHP task/session/file contract while HarnessRouter performs backend-specific translation, configuration, permissions, checkpoint ownership, event normalization and usage normalization underneath.

OpenCode is also a concrete dual-boundary example: it natively exposes ACP on the editor↔agent boundary while HarnessRouter exposes OpenCode through UHP on the product/client↔server↔harness boundary. The two interfaces should not be inferred to share transport, session semantics or implementation paths merely because the same harness can participate in both. The v1.18.31 ACP fix adds another reason to keep that boundary precise: ACP hosts depend on OpenCode correctly preserving reasoning-part identity and restored session options even though those details are not part of HarnessRouter’s UHP adapter evidence.

The v1.18.26 replay/reasoning fixes, v1.18.27 timeout/SSE/Anthropic thinking-block fixes, v1.18.28 provider-side session-correlation header, v1.18.29 Codex OAuth integer-version/model-visibility fix, v1.18.30 GPT-6 Astra-prompt, Bedrock DeepSeek-ID and provider-SDK compatibility changes, and v1.18.31 ACP restoration/reasoning-boundary fix are useful reminders that upstream harness/provider behavior can affect conversation continuity, provider compatibility, request observability, model-specific prompting and long-running turn reliability independently of the UHP layer. A backend can satisfy the same external task/session contract while still depending on upstream correctness when it serializes provider reasoning state, waits on slow provider streams, correlates provider requests, filters subscription-backed models, preserves provider-native model identifiers or obtains cloud-provider credentials. PR #139 adds the HarnessRouter-side rule that a continuation which could not restore its native OpenCode session must be surfaced as lost rather than credited as successful recall. PR #194 adds a separate persistence rule: continuity state may belong in the checkpoint tar without belonging in the workspace Git history, and nested rollback systems must not be allowed to capture one another recursively. PR #216 adds an accounting rule: when one harness exposes reasoning as a sibling of visible output, a common router must normalize those fields deliberately before comparing or billing backends.

Production users can obtain the OpenCode adapter from HarnessRouter v0.10.0 onward. Stable is now v0.19.0; PR #194’s checkpoint fix and PR #196’s later catalog/storage changes remain inherited tagged behavior. PR #216’s usage-accounting correction is current-main behavior after the stable tag. That release status still does not justify silently extending HarnessRouter’s original v1.18.23-era verification evidence to every later OpenCode build.

Section titled “Related pages”

Read HarnessRouter Community Edition for the implementation-wide view, the release tracker for release status, UHP vs ACP for the distinct editor↔agent boundary, and the adoption tracker for the difference between integration and native UHP support.

Primary sources

Section titled “Primary sources”