OpenCode
opencodeDelegate a coding task to an AI coding agent, run its first turn, and return a session ID for follow-up replies, status polling, and output retrieval.
Instructions
Use this to delegate a new coding task to OpenCode and run its first turn. Blocks until the turn finishes (or wait-seconds elapses, up to the turn timeout). The final answer and status are in structuredContent.content / structuredContent.status; the text response mirrors the same content. Returns a session id (also usable as threadId/conversationId) to continue with opencode-reply. sandbox selects a cooperative permission profile for OpenCode's own tools (read-only / workspace-write / danger-full-access) — it is not OS-level isolation, OpenCode can still run arbitrary shell commands unless a rule denies it. approval-policy controls permission prompts raised by OpenCode: never (default) auto-denies them, on-request asks interactively when the client supports it. Cancelling or stopping the call that OWNS this turn (Esc, TaskStop, a client timeout) cancels the OpenCode turn; a call that only joined an existing turn as an observer (e.g. a duplicate request-id) detaches without cancelling anything. To stop waiting but keep the turn running, pass wait-seconds and poll opencode-status. Use detail/max-output-chars to keep this response small (the full answer stays readable with opencode-output); request-id makes a retried call safe to repeat; output-schema asks the final message to be one JSON value matching a schema. To run several tasks in parallel, start each with wait-seconds:0 and check them together with opencode-status ids/wait-for.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for this session. Relative paths resolve against the server default cwd; must be inside an allowed root. Omit to use the server default cwd. | |
| agent | No | OpenCode's primary agent for this session (e.g. 'build', 'plan', or a custom agent). Omit to use the server-configured default, or OpenCode's own default agent. | |
| model | No | Model to use, in the form 'provider/model' (e.g. 'my-gateway/coder-large'), not a bare model name. Omit to use the server-configured default, or OpenCode's own resolution if none is set. | |
| title | No | Session title shown by opencode-status. Defaults to the first line of prompt (up to 80 chars). | |
| detail | No | 'compact' (default 'standard') drops toolCalls and filesChanged from this response (keeping toolCallCount, filesChangedCount, pendingApprovalCount, and pendingApprovals itself) to save context; the full answer and tool-call log stay retrievable with opencode-output regardless of this setting. | |
| prompt | Yes | The task or instructions to send to OpenCode for this turn. | |
| sandbox | No | Cooperative permission profile for OpenCode's own tools (default 'workspace-write'). Not OS-level isolation: OpenCode can still run arbitrary shell commands unless a rule denies it. Fixed for the life of the session once chosen. 'read-only' also denies file edits, bash, paths outside cwd and web fetch/search. | |
| request-id | No | Idempotency key for this exact call (pattern: starts with a letter/digit, then up to 127 more letters/digits/'.'/'_'/':'/'-'). Retrying the same request-id after a network drop or client retry joins the original operation instead of sending a second prompt to OpenCode; a different request-id (or omitting it) always starts a new one. Shared between opencode and opencode-reply. | |
| wait-seconds | No | Bounds only how long THIS call waits for a result, in seconds; it does not limit the turn itself. On expiry this call returns a 'running' (or 'waiting_for_approval') snapshot while the turn keeps executing on the server — continue observing it with opencode-status. Omit to block until the turn reaches a terminal state (subject to timeout-seconds); 0 returns immediately after admission — combine with opencode-status ids/wait-for to fan a batch of turns out in parallel and then observe them together. | |
| output-schema | No | Ask OpenCode's final message for THIS turn to be one JSON value matching this JSON Schema (subset: object/array/string/number/integer/boolean/null; no $ref or unions; see README for the full list of supported keywords). Reported back as structuredOutput / structuredOutputStatus ('valid'/'missing'/'invalid'); still untrusted model output, and never changes status, error or retry behaviour. Turn-local: never inherited by a later reply. | |
| approval-policy | No | How OpenCode permission prompts are handled (default 'never'): 'never' auto-denies them; 'on-request' asks interactively when the client supports it, otherwise also denies. Fixed for the life of the session once chosen. | |
| timeout-seconds | No | This turn's hard run-time limit, in seconds. When it expires, the OpenCode run is stopped and the result comes back with status 'timeout' — the work already done is not lost, but the turn itself ends. This is not a call timeout: to stop waiting for a response while letting the turn keep running, use wait-seconds instead. | |
| max-output-chars | No | Caps how many characters of the answer come back in THIS response only (0..44000; 0 returns no answer text at all). Never truncates the retained turn — read the rest with opencode-output. Omit to use the default for the chosen detail level (44000 standard, 2000 compact). | |
| base-instructions | No | Extra system text sent before developer-instructions. OpenCode can't replace its own base prompt per request, so this is added text, not a full override. | |
| developer-instructions | No | System-prompt text for this session; stored and re-sent on every turn, including replies. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cost | No | ||
| diff | No | ||
| hint | No | ||
| kind | Yes | ||
| turn | No | ||
| agent | No | ||
| error | No | ||
| model | No | ||
| roots | No | ||
| total | No | ||
| action | No | ||
| agents | No | ||
| finish | No | ||
| models | No | ||
| offset | No | ||
| output | No | ||
| reason | No | ||
| server | No | ||
| status | Yes | ||
| tokens | No | ||
| turnId | No | ||
| cleanup | No | ||
| content | Yes | ||
| hasMore | No | ||
| partial | No | ||
| request | No | ||
| results | No | ||
| section | No | ||
| waitFor | No | ||
| readyIds | No | ||
| sessions | No | ||
| threadId | No | ||
| warnings | No | ||
| directory | No | ||
| elapsedMs | No | ||
| sessionId | No | ||
| toolCalls | No | ||
| truncated | No | ||
| nextOffset | No | ||
| observedAt | No | ||
| pendingIds | No | ||
| snapshotId | No | ||
| availability | No | ||
| filesChanged | No | ||
| resendSafety | No | ||
| responseLoop | No | ||
| upstreamRead | No | ||
| omittedFields | No | ||
| toolCallCount | No | ||
| upstreamRetry | No | ||
| executionState | No | ||
| opencodeVersion | No | ||
| pendingApprovals | No | ||
| structuredOutput | No | ||
| filesChangedCount | No | ||
| abortedRunningTurn | No | ||
| pendingApprovalCount | No | ||
| structuredOutputError | No | ||
| structuredOutputStatus | No |