OpenCode CLI Adapter

The OpenCode adapter connects Sortie to the OpenCode CLI via subprocess management. It launches opencode run --format json, reads newline-delimited stdout envelopes, tolerates plain-text permission warnings mixed into stdout, and normalizes the stream into domain event types. Registered under kind "opencode".

Each RunTurn call spawns a fresh subprocess. One reader goroutine owns stdout, the adapter emits activity-visible events so the orchestrator stall watchdog can observe progress, per-session state is mutex-guarded, and StartSession performs no binary canary check or authentication preflight.

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.

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. Some map to OpenCode CLI flags. Others map to managed OPENCODE_* environment variables that the adapter injects on every run and export subprocess.

The adapter always adds run --format json --dir <workspace> -- <prompt>. It does not expose --attach, --port, --command, --file, --title, --continue, or --fork.

opencode:
  model: anthropic/claude-sonnet-4-5
  variant: high
  pure: true
  dangerously_skip_permissions: true
  disable_autocompact: true
  allowed_tools:
    - read
    - edit
    - glob

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 a managed permission policy from allowed_tools and denied_tools, then injects it through OPENCODE_PERMISSION. The policy is separate from --dangerously-skip-permissions.

The adapter’s known permission-key set is:

list and todowrite are included even though the public OpenCode permissions page does not list them. The adapter mirrors the runtime schema, not only the rendered docs page.

The adapter also manages these environment variables on every subprocess:

Before adding its managed value, the adapter removes any inherited OPENCODE_PERMISSION entry from the parent process environment. It does not remove permission rules from opencode.json, so OpenCode still deep-merges the adapter policy with on-disk configuration.

Session lifecycle

StartSession

Validates the workspace path, resolves the launch target, and initializes adapter-owned session state. No OpenCode subprocess is started.

1. Validates that WorkspacePath is a non-empty absolute path pointing to an existing directory.
2. Resolves the configured command via exec.LookPath, 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.
3. Copies ResumeSessionID into session state when continuation is requested.
4. Returns an opaque Session handle with per-session state, no running PID, and no started subprocess.

StartSession performs no version canary, no provider-auth probe, and no remote OpenCode binary check.

Errors:

RunTurn

Spawns one OpenCode subprocess, reads stdout through a single reader goroutine, and delivers normalized events via OnEvent.

1. Builds the managed environment and the per-turn argument list.
2. Adds run --format json --dir <workspace> to every invocation.
3. Adds --session <id> when the session already has an OpenCode session ID.
4. Launches the subprocess locally or through SSH, with cmd.Dir set to the workspace and cmd.Env set to the inherited environment plus managed OPENCODE_* overrides.
5. Configures process-group isolation before start, then sets cmd.Cancel to a graceful process-group signal and cmd.WaitDelay to 5 seconds.
6. Starts one stderr collector goroutine, one stdout reader goroutine, and one wait goroutine.
7. Applies a startup timer derived from read_timeout_ms. Plain-text stdout lines reset the timer before the first JSON envelope arrives.
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 domain events.
10. After stdout drains and the process exits, runs opencode export --sanitize <sessionID> to recover final token usage.
11. Returns a TurnResult based on the terminal error envelope, cancellation state, startup timeout, or process exit status.

StopSession

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 5 seconds for the subprocess to exit.
4. Force-kills the process group if it is still alive after the grace window.
5. Returns ctx.Err() if the caller’s StopSession context expires first.

Safe to call when no subprocess is active.

EventStream

Returns nil. The adapter delivers all events synchronously through RunTurn’s OnEvent callback.

Process shutdown

The OpenCode adapter uses exec.CommandContext, not exec.Command. This is a deliberate deviation from the earlier CLI adapters.

Before start, the adapter places the subprocess in its own process group via the shared procutil package. It also overrides cmd.Cancel to send a graceful signal to the process group and sets cmd.WaitDelay to 5 seconds. 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 AssignProcess attaches a Job Object with KILL_ON_JOB_CLOSE so force termination kills the full descendant tree.

Shutdown is turn-scoped, not session-scoped. StopSession performs an explicit graceful-to-force sequence. Turn-context cancellation is stricter: CommandContext triggers the graceful cancel hook, and the adapter’s cancellation path also force-kills the process group during teardown if the process is still alive. After cmd.Wait returns, 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. The stdout scanner allows up to 10 MB per line to accommodate large tool payloads.

Event type mapping

Result event fields

OpenCode does not emit a dedicated final result envelope. The adapter reads these terminal fields from the envelopes that determine session identity, tool status, and failure state.

Non-JSON output handling

If a stdout line fails JSON parsing and begins with ! permission requested:, the adapter emits a notification event instead of treating the line as a protocol failure. This compensates for the documented drift where OpenCode prints permission warnings to stdout before the JSON tool_use error envelope.

Any other non-JSON line becomes malformed. Before the first JSON envelope arrives, all plain-text lines still reset the startup read_timeout_ms timer.

Token accounting

The adapter does not trust step_finish.part.tokens as the final turn total. It recovers authoritative usage from a second subprocess after the main turn exits.

Accumulation logic

1. After the main opencode run subprocess exits, finalizeExitedTurn calls queryExportUsage when a session ID is known.
2. queryExportUsage launches a second subprocess with opencode export --sanitize <sessionID> in the same workspace.
3. The export subprocess runs with the same managed environment as the turn subprocess: OPENCODE_AUTO_SHARE=false, OPENCODE_DISABLE_AUTOCOMPACT=<bool>, OPENCODE_DISABLE_AUTOUPDATE=true, OPENCODE_DISABLE_LSP_DOWNLOAD=true, and optional OPENCODE_PERMISSION=<json>.
4. The export subprocess timeout is min(2 * read_timeout_ms, 30s). With the workflow default read_timeout_ms: 5000, the export timeout is 10 seconds.
5. The parser unmarshals the export JSON, scans messages in reverse order, and selects the most recent assistant message whose info.sessionID matches the current session.
6. It reads info.tokens.input, info.tokens.output, optional info.tokens.total, and optional info.tokens.cache.read.
7. total_tokens defaults to input + output when tokens.total is absent.
8. If export setup fails, the subprocess exits non-zero, the JSON is malformed, or no matching assistant message with tokens exists, usage falls back to zero. The adapter logs a warning and emits no token_usage event.

The adapter emits at most one token_usage event per turn, after the export subprocess succeeds. It does not emit any token event when every recovered token counter is zero.

Model tracking

The main stdout stream does not supply a stable final model identifier. The adapter reconstructs Model only from the export payload, using info.providerID + "/" + info.modelID when both fields are present.

Per-model attribution works only when the export payload includes both values. The adapter parses info.cost from the export payload but does not surface cost on normalized domain events.

API timing

The adapter does not emit per-request API timing and does not populate APIDurationMS 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.

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. Sets ToolError when part.state.status equals error.

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

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.

Permission rejections surface as OpenCode reports them, for example: The user rejected permission to use this specific tool call.

Error handling

Exit code mapping

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

Stdout scanner failure

If the stdout scanner returns an error while the turn is still active, the adapter:

1. Emits turn_ended_with_error with message stdout read error.
2. Stops the reader loop and kills the process group.
3. Re-emits collected stderr lines at WARN level.
4. Returns an AgentError with kind response_error.

If the scanner fails while the turn is already being cancelled or stopped, the adapter returns turn_cancelled instead.

Stall detection

The adapter does not run its own inter-event stall timer. read_timeout_ms only covers startup and waits for the first JSON envelope, 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, RunTurn tears down the process and returns 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.

The adapter never uses --continue or --fork.

If a resumed turn emits a different sessionID from the one already stored, the adapter aborts the turn with response_error and emits turn_ended_with_error. 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 the export recovery step uses a second SSH invocation.

How it works

1. StartSession resolves the local ssh binary. It does not validate the remote opencode binary at this stage.
2. RunTurn prefixes managed OPENCODE_* variables onto the remote command string.
3. sshutil.BuildSSHArgs wraps the turn command as cd -- '<workspace>' && <remoteCommand> 'run' '--format' 'json' ....
4. queryExportUsage uses the same SSH path with export --sanitize <sessionID>.

SSH options

The adapter uses the shared sshutil transport defaults:

Shell quoting

The workspace path, adapter-generated OpenCode arguments, and managed environment-variable values are single-quoted with standard POSIX escaping before they are embedded in the remote shell command. The configured remote base command itself is treated as a pre-formed shell fragment. Quoting inside agent.command is the operator’s responsibility.

Exit codes

SSH exit codes 255 and 127 are not special-cased. They fall through the adapter’s generic non-zero process-exit branch and map to port_exit unless OpenCode already emitted a terminal stdout error envelope. Exit code 0 is still not sufficient to prove success, because OpenCode can emit a terminal error envelope and still exit 0.

Authentication

In local mode, the adapter launches OpenCode with the parent process environment plus managed OPENCODE_* overrides. OpenCode then resolves provider credentials from its own environment, auth store, project .env, or opencode.json provider config. In SSH mode, the adapter prefixes only managed OPENCODE_* variables on the remote command. Provider credentials are not forwarded to the remote host.

StartSession performs no authentication preflight. It checks no provider environment variables and does not call opencode providers, opencode auth, or any provider-specific login command.

The research notes explicitly evidence these provider environment-variable families and configuration entry points:

Concurrency safety

The adapter is safe for concurrent use. One OpenCodeAdapter instance serves all sessions. Per-session state is isolated in the opaque Session.Internal handle.

Within a session, a mutex guards the stored session ID, closed flag, and active turn runtime. One reader goroutine owns stdout. A separate wait goroutine does not call cmd.Wait until the reader goroutine finishes draining stdout, then stores the result behind waitMu and closes waitCh. This prevents cmd.Wait from racing the scanner on the stdout pipe.

Adapter registration

The adapter registers itself under kind "opencode" via an init function in internal/agent/opencode. Registration metadata declares:

The orchestrator’s preflight validation uses this metadata to require a non-empty agent.command field for agent.kind: opencode. Binary lookup still happens during StartSession via exec.LookPath.

Key differences from other adapters

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