OpenCode CLI Adapter

The OpenCode adapter connects Sortie to the OpenCode CLI via subprocess management. It runs OpenCode 2.x, published on npm as @opencode/cli, and checks at the start of every session that agent.command reports a 2.x version; see version check. It launches opencode run --format json, reads newline-delimited stdout envelopes, reads the runtime’s permission warnings from stderr, and normalizes the stream into Sortie’s own event vocabulary. Registered under kind "opencode".

Each turn spawns a fresh subprocess. The adapter emits activity-visible events so the orchestrator stall watchdog can observe progress. Session start does run a version query (see version check), but that query checks no credential and performs no authentication preflight. The CLI accepts no MCP configuration path, so on a local launch the adapter translates the generated configuration into OpenCode’s own form and delivers it in the turn’s environment; see MCP.

See also: WORKFLOW.md configuration for the full agent schema, environment variables for runtime environment behavior, error reference for all agent error kinds, how to write a prompt template for template authoring.

Configuration

The adapter reads from two configuration sections in WORKFLOW.md front matter: the generic agent block (shared by all adapters) and the opencode extension block.

Version check

Session start runs the configured command with --version, bounded the same way the post-turn export launch is (see read_timeout_ms below), and reads only the first non-empty line of the output. It scans that line’s whitespace-separated fields, dropping one leading v from each, for the first one that matches a bare semantic version, and requires that version’s leading number to be 2.

A version on a later line is never found: if the first non-empty line carries no such field, or the output was truncated, the check fails. The check runs once per session, over SSH when the launch is remote, and is never repeated or cached. A later major than 2 fails the check like any other, so install @opencode/cli@2 to stay on a supported major.

Errors:

agent section

These fields control the orchestrator’s scheduling behavior. They are not passed to the OpenCode CLI.

agent:
  kind: opencode
  command: opencode
  max_turns: 5
  max_sessions: 3
  max_concurrent_agents: 4
  stall_timeout_ms: 300000
  max_concurrent_agents_by_state:
    in progress: 3
    to do: 1

opencode extension section

These fields are adapter-specific. Each maps to a CLI flag or to a member of the inline configuration document the adapter delivers in OPENCODE_CONFIG_CONTENT; see managed environment.

The adapter always adds run --format json --standalone, and delivers the prompt on standard input.

opencode:
  model: <provider>/<model-id>
  effort: high
  dangerously_skip_permissions: true
  disable_autocompact: true
  allowed_tools:
    - read
    - edit
    - glob

Settings refused at session start

Session start refuses the settings below before it launches anything. Each fails with error kind agent_not_found and starts no subprocess.

The overlap and the effort/variant conflict are also validate-time checks.

agent.max_turns vs. OpenCode inner turn scope

The adapter exposes no OpenCode-specific inner turn or step-budget field.

Use turn_timeout_ms to bound wall-clock time for a single turn. There is no adapter-level cap on OpenCode’s internal step count within that turn.

Permission policy

The adapter synthesizes one managed permission policy from allowed_tools and denied_tools and injects it as the permission member of the inline configuration document (see managed environment). The policy is separate from the --dangerously-skip-permissions flag, but with dangerously_skip_permissions: false the adapter also writes a policy when both lists are empty; see access outside the workspace.

The adapter’s known permission-key set is:

This is the set this version of the adapter knows about, not a catalogue of OpenCode’s tools. A key OpenCode adds later is unknown to the adapter until the adapter learns it, and an unknown key you write is forwarded unchanged. The adapter forwards every key unchanged, so a key takes effect only where the runtime itself recognizes it.

Access outside the workspace

With dangerously_skip_permissions: false, the agent cannot read or write files outside the session workspace unless you allow it. The runtime refuses the access and reports it to the model like any other refused tool call. To allow it, name external_directory in allowed_tools.

A non-empty allowed_tools denies every known key it does not list, so list each tool the agent needs (read, edit, bash, and so on) alongside external_directory. The other way to allow it is dangerously_skip_permissions: true, which approves every permissioned call and not only this one.

The adapter decides external_directory as follows:

On a local launch, an external_directory rule in your own OpenCode configuration files does not apply in this mode, because the adapter writes a value for the key and its document loads last; see managed environment. On an SSH worker, an OPENCODE_PERMISSION value set in the remote login environment is applied after the adapter’s document and wins for every key it names.

Managed environment

The adapter sets one environment variable on every subprocess it launches, the version check, the usage export, and the credential-verification session delete included:

Sharing, compaction, the permission policy, and tool servers ride together in one inline configuration document, delivered through OPENCODE_CONFIG_CONTENT on every turn, local or remote, whether or not the session carries tool servers.

share is always "disabled". compaction.auto is false only when opencode.disable_autocompact is true. permission carries the policy above and mcp carries the translated tool servers, a member present when the session delivers any; see MCP. agent.title.disable is true, the title-agent switch described in Token accounting.

A remote turn carries the same document. When the launch requests a reverse forward, the whole document is sent once the forward’s remote port is known, because the mcp member names that port. The version check, usage export, and session delete invocations never carry it, on either kind of launch.

The credential-verification session’s document sets permission to deny every tool, whatever opencode.allowed_tools, opencode.denied_tools, and opencode.dangerously_skip_permissions say, so the request carries no tool definitions, calls no tool, and writes nothing into the issue workspace. The check makes one model request. It still carries the instruction files and the built-in system prompt, because the runtime offers no switch that drops them. When the check falls back to the full context, it uses the configured policy.

On a local launch, before adding its managed values, the adapter strips OPENCODE_AUTO_SHARE, OPENCODE_DISABLE_AUTOCOMPACT, OPENCODE_DISABLE_AUTOUPDATE, OPENCODE_DISABLE_LSP_DOWNLOAD, OPENCODE_PERMISSION, and OPENCODE_CONFIG_CONTENT out of the inherited environment, so an operator-side value never reaches the subprocess. It does not remove permission rules from opencode.json, so OpenCode still deep-merges the adapter policy with on-disk configuration, the adapter’s own document loading last.

On a remote launch the adapter strips nothing. It sends its own OPENCODE_CONFIG_CONTENT, which replaces any value of that name in the remote login environment, and leaves every other variable there, OPENCODE_PERMISSION included, as it finds it.

Validate-time checks

When agent.kind is opencode, the sortie validate pipeline runs OpenCode-specific config checks in addition to the generic preflight validation. They build no adapter and launch no subprocess, and the same checks run at startup and on every workflow reload, so the verdict is identical in all three places.

Errors

Session start reports each of these with the same message, so the two paths can never disagree.

Warnings

This is a warning rather than an error. Warnings leave valid true and the exit code 0. The runtime refuses the request itself, so the setting never leaves a turn waiting for a person; it does stop the agent from using any permissioned tool. A refusal reaches the model as an errored tool result, and the turn continues. An absent or true value draws nothing.

Session lifecycle

Session start

Refuses unusable settings, validates the workspace path, resolves the launch target, checks the OpenCode version, and initializes adapter-owned session state. No turn subprocess is started, but the version query below does start and exit a subprocess of its own, and so does the session export a continued session reads.

1. Refuses the settings listed under settings refused at session start.
2. Validates that the workspace path is a non-empty absolute path pointing to an existing directory.
3. Resolves the configured command from PATH, defaulting to opencode when agent.command is empty. In SSH mode, resolves the local ssh binary instead and stores the remote command string for later use.
4. Resolves the session’s tool delivery from the generated MCP configuration, on a local launch and an SSH launch alike. On an SSH launch this starts Sortie’s HTTP tool server and opens one short extra SSH connection to learn whether the worker host accepts the reverse forward. See MCP.
5. Queries the resolved command’s version, over SSH when the launch is remote, and refuses the session when it is unreadable or not a 2.x release; see version check.
6. When continuation is requested, reads the saved session’s export, over SSH when the launch is remote, to fix the session’s earlier spend as history; see resumed sessions. A failed read does not fail session start.
7. Builds the inline configuration document every turn of the session will carry, from the settings and the tool servers resolved in step 4.
8. The session has no running process ID or subprocess yet, and takes the session ID saved from a previous run as its own when continuation is requested.

Session start performs no provider-auth probe.

Errors:

Turn

Spawns one OpenCode subprocess, reads its stdout, and delivers normalized events to the orchestrator.

1. Builds the managed environment and the per-turn argument list.
2. Adds run --format json --standalone to every invocation and delivers the prompt on the subprocess’s standard input. --standalone keeps the launch from joining a shared background service another client started.
3. Adds --session <id> when the session already has an OpenCode session ID.
4. Launches the subprocess locally or through SSH, with the full parent process environment plus the managed environment, which includes OPENCODE_CONFIG_CONTENT on every turn. On a local launch, PWD in that environment names the same verified workspace path the subprocess’s own working directory is set to, so the subprocess lands in the workspace.
5. Isolates the subprocess in its own process group before start, then arms a graceful process-group signal for cancellation, bounded by stop_grace_ms.
6. Reads stdout and stderr concurrently while waiting for the subprocess to exit.
7. Applies a startup timer set to the larger of read_timeout_ms and 60 seconds. A stdout line that fails to parse as a JSON envelope still resets the timer before the first accepted envelope arrives, but does not itself count as the runtime having responded; see early exit report.
8. On the first JSON envelope with sessionID, adopts the session ID if unset or verifies it matches the resumed session. Emits session_started once per session.
9. Maps JSON envelopes and tolerated plain-text lines into events.
10. Once the subprocess has been reaped, gives stderr collection up to five seconds to finish, then gives whatever stdout is still in flight another five seconds to arrive, before settling token usage from the turn’s step reports and the session export, opencode session export --standalone --sanitize <sessionID>; see Token accounting.
11. The turn ends based on the terminal error envelope, cancellation state, startup timeout, or process exit status.

A turn that instead ends by cancellation, a read timeout, or a stdout read error still attempts this export before reporting its outcome; see Accumulation logic for the one ending that does not.

Session stop

Marks the session closed and terminates the currently running turn subprocess, if any.

1. Marks the session closed and detaches the active turn runtime from session state.
2. Sends a graceful process-group signal when a turn is still running.
3. Waits up to stop_grace_ms for the subprocess to exit.
4. Force-kills the process group if it is still alive after the grace window.
5. Reports the orchestrator’s own deadline error instead of a clean stop if that deadline expires first.
6. On a credential-verification session that reached a session ID, runs opencode session delete --standalone <id> in the workspace before returning. A failed delete, including exit 1 for an identifier the runtime does not recognize, is only logged; it never fails the run.

Safe to call when no subprocess is active.

Process shutdown

Before start, the subprocess is isolated in its own process group. A graceful process-group signal is armed for cancellation, bounded by stop_grace_ms. On Unix, graceful shutdown is SIGTERM and force kill is SIGKILL to the process group.

On Windows, graceful shutdown is CTRL_BREAK_EVENT to the process group, and the subprocess is assigned to a Job Object with KILL_ON_JOB_CLOSE so force termination kills the full descendant tree.

The subprocess starts suspended and is resumed only after that assignment succeeds, so nothing it spawns can run before the job takes effect; this covers the auxiliary launches described below, not only turns. A failed assignment logs WARN process group assignment failed and the launch runs without a job; a failed resume logs WARN process resume failed and reports port_exit. A failure to start the subprocess or to create its stdout or stderr pipe reports port_exit too.

A launch whose context is already done when the resume is reached, by cancellation or by its deadline, is never resumed: Sortie terminates the subprocess before it runs and logs no resume warning. A turn ends this way as turn_cancelled.

Shutdown is turn-scoped, not session-scoped. Session stop performs an explicit graceful-to-force sequence. Turn cancellation is stricter: when the turn is cancelled, the graceful signal fires immediately, and the adapter’s cancellation path also force-kills the process group during teardown if the process is still alive. After the subprocess exits, the adapter performs a best-effort group kill to clean up surviving children.

Event stream

The adapter reads stdout as newline-delimited envelopes. Most lines are JSON objects from opencode run --format json. Permission rejection warnings can also appear as plain text on stdout even in JSON mode. Reading stdout allows lines up to 10 MB long, to accommodate large tool payloads.

What the adapter emits

The adapter maps each envelope onto Sortie’s normalized event vocabulary, so what reaches the orchestrator, the logs, and the dashboard is the same set of events every adapter produces. OpenCode’s own envelope types and their fields are OpenCode’s to define; see external references.

Two behaviours are the adapter’s own. Every stdout line that fails to parse becomes a malformed event, truncated, rather than failing the turn, and it still resets the startup read timer, but it does not count as the runtime having responded; see early exit report. A permission request the runtime refuses surfaces twice, as a tool_result carrying the tool error and as a notification; no consent was granted, and the refusal does not end the turn. Sortie scans stderr for those refusals only after the process exits.

Token accounting

The adapter reads token usage from two sources, and Sortie’s usage component settles each turn from them. The live source is the tokens object of each step_finish report on stdout: one report per model request, identified by the part’s id. The records source is the session export, opencode session export --standalone --sanitize <sessionID>, which a second subprocess prints once the turn’s subprocess is gone: one assistant message per finished request, with that request’s tokens, model, and cost. Both sources count the same requests, so their figures are never added. Reported counts are cumulative over the whole session the orchestrator opened, across every turn of it, and never decrease.

The adapter disables OpenCode’s title agent by setting agent.title.disable to true in the OPENCODE_CONFIG_CONTENT document, so a turn makes no session-title request. That request is billed by the provider but recorded in no assistant message, so neither source would have counted it. The session keeps OpenCode’s default title. A remote turn carries the same document, so it makes no title request either.

For how provenance, completeness, and lower bounds work across every agent kind, see spend measurement. For this kind’s declaration beside every other kind’s, see the usage reporting table.

Accumulation logic

1. Once the main opencode run subprocess has exited or been killed and waited for, the adapter runs the session export when a session ID is known, in the same workspace. This runs on every turn ending: normal completion, a non-zero exit, a stdout error envelope, cancellation, a read timeout, and a stdout read error. A session ID mismatch is the one ending that does not run it, because the work ran in a session other than the one the export would read.
2. A session ID, once learned, persists for the rest of the session: either from a resumed session’s saved ID, or from the first JSON envelope, in this turn or an earlier one, that carries one. A read timeout recovers a figure only on a resumed session or a later turn, because it fires only before that turn’s own first JSON envelope arrives, so it never recovers one on the first turn of a new session. Cancellation and a stdout read error on that same first turn recover a figure only if an envelope carrying the session ID had already arrived before the turn ended.
3. The export subprocess runs with only OPENCODE_DISABLE_AUTOUPDATE=true. It never carries OPENCODE_CONFIG_CONTENT, so it never carries the tool policy or the tool servers either.
4. agent.read_timeout_ms bounds the turn’s whole read: the session’s export and the export of every subagent session the turn ran. With the workflow default of 5000, that read has 5 seconds. An export that runs out of time counts as failed.
5. The adapter refuses an export larger than 64 MiB, one that is not valid JSON, and one whose own info.id is not the current session. From an accepted export it takes every assistant message whose finish field is present and non-empty, not just the most recent message. A message with an empty or absent finish is excluded regardless of its token counts: OpenCode saves an assistant message with zero tokens before it calls the model, so a turn killed mid-request exports a placeholder, not a measurement. Each message carries type, finish, tokens, model, and cost at its own top level. On a resumed session, the messages the session held before the run are history and never count.
6. From each step report and each message it reads tokens.input, tokens.output, tokens.reasoning, tokens.cache.read, and tokens.cache.write. Every one must be present and an integer. A count that is absent, null, or not an integer makes the report or message unknown, never zero, and so does a missing tokens object or a reading with no input and no output tokens.
7. input_tokens is input + cache.read + cache.write; output_tokens is output + reasoning. cache_read_tokens and cache_write_tokens carry the two cache counts separately as disjoint subsets of input. total_tokens is computed as input_tokens + output_tokens rather than read from tokens.total, which counts cache and reasoning tokens on a different basis.

How a turn settles depends on the step report that ends it, a step_finish whose reason is anything other than tool-calls:

Some OpenCode 2.x releases print no step_finish for a turn’s final text step, so on those releases the export settles every completed turn. An unknown step report keeps its turn from settling on step reports. An unknown export message stops the count at that message: the messages before it count, and the turn is a lower bound.

A later turn whose export holds requests an earlier turn left uncounted counts them, so the run’s total converges on the export’s. A failed or empty export never lowers a figure the run has already reported. A failed export logs one DEBUG record, opencode session export failed, with the error and never the export’s content; a failed subagent export adds child_session_id.

The adapter emits at most one token_usage event per turn, when the turn produces a figure. A session is recorded as measured once any of its turns produces one, a lower bound included; a session no turn produced a figure for is recorded as unmeasured.

A turn that served model output counts toward unaccounted_turns unless its figure is complete. That leaves out a turn that settled on a lower bound or produced no figure, and every turn the runtime did not end itself: one that was stopped, failed, or cut short. A later turn settled complete from the export takes in the turns before it that the runtime completed, and they stop counting, unless a stopped or failed turn came between. No later turn does this once a turn has run short of a subagent session’s records, or once a resumed session’s history was fixed at a turn’s end.

Subagent sessions

A turn that hands work to a subagent runs that work in a child session. The stream shows one tool_use for the call, with state.input.agent set and the child’s session ID at state.metadata.metadata.sessionID, and no event from the child. The parent’s export holds none of the child’s messages, so at the end of the turn the adapter also exports every child session the turn named, once each, through the same command and under the same bound. Each child message counts once, in the turn that ran it, toward the run’s total, agent.max_tokens, and the cost limits, and joins the per-model split under its own model. The journal source then appears in the turn’s provenance beside the source that settled the parent’s own figure.

The turn is complete only when every subagent call completed, named its session, and had its export read with every message known. Otherwise the turn is a lower bound, and the child sessions that did read still count.

Resumed sessions

When a session continues a saved OpenCode session, session start reads that session’s export once, under the same read_timeout_ms bound. Every message it holds becomes history, matched by message ID whatever its creation time, so the session’s earlier spend never lands in this run’s total. A new session starts with no history and needs no read.

When that read fails, the history is unknown rather than empty. A turn the final step report settles still counts its own requests, but no other turn can count from the export until a turn-end export is read; that read fixes the history after its turn settles, so those turns stand as lower bounds.

Model tracking

The main stdout stream does not supply a stable final model identifier, and the step reports name no model. The adapter reads the model from the export only: each counted message’s model.providerID and model.id, joined as providerID/modelID. Each counted message adds to a per-model count under that key, and the turn’s reported model is the one with the largest share of the tokens the turn split. A message whose payload lacks either value adds to no entry, so per-model attribution works only when the export includes both (see the model label).

Reported cost

Sortie reads each counted message’s cost as that request’s amount in US dollars, under the message’s model. It never reads the cost of a step_finish report or the export’s session-level cost. The rates in force (token_rates over the price table) price every model they list from the normalized token counters; a model they do not list is priced at its reported amount.

A model’s amount is a lower bound when a counted message’s cost is absent, null, negative, or 0 beside tokens, as a free model reports it, when the turn’s figure carries no per-model split, and when a subagent session ran on that model, because a child session’s cost is never added to the parent’s. A cost priced from a lower-bound amount is recorded as partial.

API timing

The adapter does not emit per-request API timing and does not report how long an API request took on completion, failure, or token events. The export subprocess runs after the main turn exits inside its own timeout window, but its duration is not surfaced as a separate metric.

Usage limits

When each turn ends, the adapter runs opencode api experimental.usage.limits and reports the limits of the signed-in OpenCode console subscription. The command answers from OpenCode’s own sign-in, uses OpenCode’s background service, and starts it when it is not running. It runs on the host that runs the agent, the worker host for an SSH worker, and Sortie’s host contacts no other host for it. A turn that was cancelled or timed out runs nothing. A failed command reports nothing and leaves the limits already reported in place.

The share used is the limit’s percent, and the reset time is its resetsAt. A limit the console marks as limited has status exhausted; every other limit has no status.

The adapter stops asking for the rest of the session when the command cannot answer: a release without the command, an OpenCode that is not signed in to its console, or a command that outlives its timeout. An account with no console subscription reports nothing.

A free usage limit that a run reaches is reported separately, from the run’s error event, as Free usage limit with status exhausted. The error’s retry delay gives its reset time. See free-tier refusals.

Tool call tracking

Correlation

OpenCode’s CLI envelope already carries terminal tool state. The adapter does not correlate a start event with a later completion event.

1. Parses the tool_use envelope.
2. Reads the tool name from part.tool.
3. Computes duration from part.state.time.end - part.state.time.start.
4. Marks the tool result as an error when part.state.status equals error, compared case-insensitively.

callID is parsed but not used for cross-event correlation.

Tool kind and argument

Each tool_result event also carries the kind of work the tool did and its one main argument, read from part.state.input, for five tools:

For a skill call the argument is the skill’s name. Any other tool name carries the name alone, with no kind and no argument. A call whose input is not an object, or whose named member is absent or not a string, carries the kind and no argument. The adapter reads no other input member, so the argument never carries the call’s other inputs.

The served members are in the HTTP API reference, and how they show is in the session view.

Tool error detail

When part.state.status is error, the adapter copies part.state.error into the normalized event message and truncates it to 500 runes. It does not strip XML wrappers, ANSI sequences, or stderr text.

A rejected permission request reaches the message field as whatever the runtime wrote into part.state.error; the adapter neither recognizes nor rewrites that text. The separate notification for a rejection comes from a stderr line beginning ! permission requested:, matched after the process exits and after the escape sequences the runtime styles that line with are stripped.

Error handling

Turn outcome

An error kind is absent only on a turn_completed outcome; every other outcome carries one.

The adapter never trusts exit code 0 as sufficient proof of success. A terminal stdout error envelope is authoritative.

Free-tier refusals

OpenCode’s hosted free-tier model refuses any request whose tool set lacks its shell tool or its read tool, and that refusal reaches the adapter as the stdout error envelope row above rather than as the permission-refusal notice.

When the session’s own opencode.allowed_tools or opencode.denied_tools is what denied one or both of bash and read, the adapter appends a clause naming the denied tool (or tools) to the vendor’s own refusal text; a refusal from a model that is not free-tier limited, or from tool settings that do not touch either required tool, gets no such clause.

The recognition depends on the vendor’s current error wording, so an upstream rewording can make the clause stop appearing without changing the underlying refusal.

Masked failures

One failure can surface as two stdout error envelopes: one carrying the actionable diagnostic and one carrying OpenCode’s generic placeholder, Unexpected server error. Check server logs for details.. Their order on the stream is not guaranteed, so the adapter keeps whichever carries detail. When the placeholder is the only failure detail on the stream, it reaches the operator unchanged, and the adapter does not try to name the cause.

Stdout read failure

If reading stdout encounters an error while the turn is still active, the adapter:

1. Stops reading and kills the process group.
2. Settles token usage from the step reports and the session export, the same as any other turn ending; see Accumulation logic.
3. Re-emits collected stderr lines at WARN level.
4. Emits turn_failed with message stdout read error: <detail> and reports an error of kind port_exit with the text stdout scanner error.

If a cancellation or stop had already begun when the adapter killed the process, the turn ends as turn_cancelled instead: stderr is not re-emitted, but the process is still killed and usage is still recovered the same way.

Stall detection

The adapter does not run its own inter-event stall timer. The first-envelope wait, the larger of read_timeout_ms and 60 seconds, only covers startup, although plain-text stdout lines reset that timer before the first JSON line arrives.

After the first JSON envelope, stall detection is orchestrator-owned. The adapter emits notification or malformed events for plain-text warnings, unknown JSON types, and normal OpenCode envelopes so the orchestrator’s stall_timeout_ms watchdog can observe output activity. When the orchestrator cancels a stalled turn, the adapter tears down the process and the turn ends as turn_cancelled.

Session resume mechanism

OpenCode continuation is flag-based. The adapter persists the OpenCode session ID and passes it back on the next subprocess launch.

If a resumed turn emits a different sessionID from the one already stored, the adapter aborts the turn with response_error, stops the subprocess gracefully, and emits turn_failed. session_started is emitted only once per session, on the first accepted JSON envelope.

SSH remote execution

When the worker configuration includes ssh_hosts, the adapter launches the local ssh client and runs OpenCode on the remote host. The process model stays launch-per-turn: each turn is a separate SSH invocation that wraps one remote opencode subprocess, and each session export, the turn’s own and any subagent session’s, uses another SSH invocation.

How it works

1. Session start resolves the local ssh binary, then runs the remote command’s version query over that same SSH path to check its OpenCode version; see version check. A version query failure fails session start the same way it does on a local launch, and needs the remote host’s dd utility (step 4).
2. Each turn sends OPENCODE_DISABLE_AUTOUPDATE and the inline configuration document in OPENCODE_CONFIG_CONTENT to the remote shell on the SSH session’s standard input, together with any variable worker.ssh_pass_env names. The document carries the same members a local turn’s does, the tool servers included; see managed environment and MCP. A turn that delivers Sortie’s tools also sets SORTIE_TOOL_SERVER_BEARER and any SORTIE_MCP_HEADER_<n> variables the same way.
3. The remote shell enters the workspace, exports what the launch sent it, and only then runs the configured command with the turn’s arguments, each step chained on the success of the one before it.
4. Because every remote launch on this kind sends the managed variables, every remote host needs the standard dd utility. A host without it fails the launch with sortie: dd is required on the remote host to receive environment variables on standard error.
5. Each session export uses the same SSH path with the export arguments described in Token accounting, so a remote turn is measured the same way as a local one.
6. When Sortie stopped the turn, by cancellation, a timeout, or shutdown, the turn waits over a second SSH connection for the remote OpenCode process tree to exit before it runs the export, for at most one second plus agent.stop_grace_ms rounded up to whole seconds. That wait needs the flock utility on the remote host. Without it the export can run while the stopped process still holds OpenCode’s session database, fail, and leave the turn’s step reports as a lower bound; the next turn’s export counts the rest.

SSH options

The adapter uses the shared sshutil transport defaults. A launch that delivers Sortie’s tools adds a reverse forward and the options that go with it; see delivery over SSH.

Shell quoting

The workspace path and the adapter-generated OpenCode arguments are single-quoted with standard POSIX escaping before they are embedded in the remote shell command. A string agent.command is treated as a pre-formed shell fragment, so quoting inside it is the operator’s responsibility; each element of a list command is single-quoted. Environment-variable values are not part of that command string.

Exit codes

SSH exit code 255 indicates a connection failure and maps to port_exit unless OpenCode already emitted a terminal stdout error envelope. Exit code 127 means the remote binary is not in PATH; the process wrote nothing to stdout, so the turn takes the early exit report under port_exit, carrying exit status 127 and the remote shell’s own message. Exit code 0 is still not sufficient to prove success, because OpenCode can emit a terminal error envelope and still exit 0.

Authentication

Sortie does not manage OpenCode credentials and runs no authentication preflight for this adapter. The subprocess inherits the Sortie process environment, so whichever provider credentials OpenCode expects must already be present there. Which providers OpenCode supports, and which variable each one reads, is OpenCode’s to document; see external references.

MCP

The OpenCode CLI accepts no MCP configuration path as an argument, and it does not read the mcpServers key the generated .sortie/mcp.json is written under.

The adapter delivers the servers rather than the file: session start reads the generated configuration and renders its servers into OpenCode’s own server-entry shape, keyed under mcp, with a stdio server becoming a local entry and an HTTP server a remote one. A server entry that omits its enable flag is rendered enabled, matching the runtime’s own default. An HTTP entry names each header value by an environment variable, {env:SORTIE_MCP_HEADER_<n>}, instead of holding it; Sortie sets those variables in the turn’s environment.

The turn sets those entries on the turn subprocess through the runtime’s inline-configuration environment variable, OPENCODE_CONFIG_CONTENT. The mcp entries live inside the one inline document that also carries the tool policy, sharing, and compaction (see managed environment), so the variable is set whether or not the session carries servers.

The runtime merges the document with whatever project or global configuration the operator already has, rather than replacing it, and the auxiliary export and session delete invocations the adapter also runs rebuild their environment without it, so none of them spawns a tool sidecar of its own. Any OPENCODE_CONFIG_CONTENT inherited from the orchestrator’s own environment is stripped first, on every one of those.

Tool servers over SSH

A remote turn carries the same document with an mcp member that differs from a local one. sortie-tools is a remote entry at the address of the launch’s reverse forward, with an Authorization header of Bearer {env:SORTIE_TOOL_SERVER_BEARER}. Servers from mcp_config that run as a local program (stdio) are left out. Operator HTTP servers appear with their URLs.

The document is sent on the SSH session’s standard input after the forward’s remote port is known. If the worker host refuses the forward, the document carries no sortie-tools entry, the session declares a gap, and its first-turn prompt carries no tool advertisement. See delivery over SSH for the forward, the bearer, and the gap reasons. The rest of the document, the permission policy, sharing, compaction, and the title-agent switch, applies as it does locally. OPENCODE_DISABLE_AUTOUPDATE reaches the session too, and so does anything worker.ssh_pass_env names.

Startup failures

The run projection this adapter reads carries no MCP startup signal, so a server that fails to start produces no distinct diagnostic here. It surfaces only indirectly, as the agent’s own tool calls failing. OpenCode starts every configured server without waiting for a tool call first: it starts each server’s connection in the background while it prepares the session, without waiting for either the process to spawn or the connection to finish before the turn proceeds.

mcp_config

opencode.mcp_config names an operator-supplied MCP server configuration file. The worker reads it, merges its servers with the sortie-tools entry into the generated copy, and the adapter translates the merged result, so an operator’s own servers reach an OpenCode session alongside Sortie’s. Over SSH only the HTTP servers reach it. A relative path resolves against the directory containing WORKFLOW.md. An unreadable path, a file that is not valid JSON, or a file already declaring a server named sortie-tools fails the attempt before the session starts.

Two more conditions fail the session with response_error when the merged configuration reaches the adapter, and the message names the offending server: an entry that carries neither command nor url, carries both, or declares a type contradicting the fields it carries; and an entry carrying a key outside the modeled set, which is type, command, args, env, url, headers, and enabled.

Both come from shared validation, so a file that fails here fails a codex session the same way.

Key differences from other adapters

External references

• OpenCode CLI documentation: official command reference for opencode run, opencode export, and session flags
• OpenCode configuration reference: opencode.json schema, provider auth store, and permission policy fields
• anomalyco/opencode on GitHub: source repository, releases, and issue tracker
• OpenCode permissions documentation: semantics of the permission policy this adapter synthesizes

Related pages

• WORKFLOW.md configuration reference: full agent schema and opencode extension block
• Environment variables reference: runtime environment behavior and configuration overrides
• Error reference: all agent error kinds with retry behavior
• How to control agent costs: orchestrator-level cost caps that matter most for OpenCode
• How to scale agents with SSH: remote execution setup and host pool configuration
• How to write a prompt template: template variables, conditionals, and built-in functions
• State machine reference: orchestration states, turn lifecycle, and stall detection