The best way to control Claude Code, Codex and more from any computer or phone
fix(opencode): support explicit background waits (#35272)
Co-authored-by: Julius Marminge <julius0216@outlook.com>
Andrei Shenets committed
Nov 14, 2026 at 08:29 UTC
6d94997008fb29d9286654ff976ba7d3f05b6bf6
4 files changed
+119
-3
apps/server/src/mcp/toolkits/orchestrator/tools.ts
+1
-1
@@ -142,7 +142,7 @@ const WorkflowStopTool = Tool.make("t3_workflow_stop", {
142
143
const BackgroundWaitTool = Tool.make("t3_background_wait", {
144
description:
145
- "Keep this thread in Working while background work runs. Pass its task ID after starting it. Not for work left running (dev server, watcher). `waiting=false` clears. Does not stop the task. Claude only.",
145
+ "Keep this thread in Working while background work runs. Pass its task ID once started. Not for work left running (dev server, watcher). `waiting=false` clears. Doesn't stop tasks. Claude/OpenCode only.",
146
parameters: Schema.Struct({
147
taskIds: Schema.Array(TrimmedNonEmptyString).check(
148
Schema.isMinLength(1),
apps/server/src/orchestration-v2/Adapters/OpenCode2AdapterV2.test.ts
+85
-1
@@ -327,6 +327,7 @@ const resumed = (
327
readonly version?: "2.2.1" | "2.2.5" | "2.2.6";
328
readonly shellRecovery?: ReadonlyArray<ProviderReplayEntry>;
329
readonly lastRunOrdinal?: number;
330
+ readonly pendingBackgroundTasks?: OrchestrationV2ProviderThread["pendingBackgroundTasks"];
331
readonly goal?: OrchestrationV2ProviderThread["goal"];
332
readonly external?: boolean;
333
readonly supervised?: boolean;
@@ -396,6 +397,9 @@ const resumed = (
397
? {}
398
: { lastRunOrdinal: options.lastRunOrdinal }),
399
...(options?.goal === undefined ? {} : { goal: options.goal }),
400
+ ...(options?.pendingBackgroundTasks === undefined
401
+ ? {}
402
+ : { pendingBackgroundTasks: options.pendingBackgroundTasks }),
403
},
404
threadId,
405
modelSelection: bigPickle,
@@ -1017,6 +1021,10 @@ it.layer(McpProviderSessions.layer)("OpenCode2 adapter", (it) => {
1021
const terminal = yield* runtime.events.pipe(
1022
Stream.tap((e) =>
1023
Effect.gen(function* () {
1024
+ if (e.type === "provider_thread.updated") {
1025
+ for (const task of e.providerThread.pendingBackgroundTasks ?? [])
1026
+ assert.isUndefined(task.awaited);
1027
+ }
1028
if (e.type !== "turn_item.updated") return;
1029
items.push(e.turnItem);
1030
if (e.turnItem.type === "command_execution" && e.turnItem.output === "retained\n")
@@ -1034,6 +1042,43 @@ it.layer(McpProviderSessions.layer)("OpenCode2 adapter", (it) => {
1042
}
1043
yield* Fiber.join(terminal);
1044
assert.isTrue(yield* runtime.hasPendingBackgroundWorkForThread!(thread));
1045
+ for (const awaited of [true, false, true]) {
1046
+ const roster = yield* runtime.events.pipe(
1047
+ Stream.filter(
1048
+ (e) =>
1049
+ e.type === "provider_thread.updated" &&
1050
+ e.providerThread.pendingBackgroundTasks?.some(
1051
+ (task) => task.taskId === shellID && (task.awaited === true) === awaited,
1052
+ ) === true,
1053
+ ),
1054
+ Stream.runHead,
1055
+ Effect.forkScoped,
1056
+ );
1057
+ assert.deepEqual(
1058
+ yield* runtime.awaitBackgroundTasks!({
1059
+ providerThread: thread,
1060
+ taskIds: [shellID, shellID, "sh_unknown"],
1061
+ awaited,
1062
+ }),
1063
+ { matched: [shellID] },
1064
+ );
1065
+ yield* Fiber.join(roster);
1066
+ }
1067
+ assert.deepEqual(
1068
+ yield* runtime.awaitBackgroundTasks!({
1069
+ providerThread: {
1070
+ ...thread,
1071
+ nativeThreadRef: {
1072
+ driver: OPENCODE_PROVIDER,
1073
+ nativeId: "ses_foreign",
1074
+ strength: "strong",
1075
+ },
1076
+ },
1077
+ taskIds: [shellID],
1078
+ awaited: false,
1079
+ }),
1080
+ { matched: [] },
1081
+ );
1082
const settled = yield* runtime.events.pipe(
1083
Stream.tap((e) =>
1084
Effect.sync(() => {
@@ -1058,6 +1103,14 @@ it.layer(McpProviderSessions.layer)("OpenCode2 adapter", (it) => {
1103
else gate.release("shell-exit");
1104
yield* Fiber.join(settled);
1105
assert.isFalse(yield* runtime.hasPendingBackgroundWorkForThread!(thread));
1106
+ assert.deepEqual(
1107
+ yield* runtime.awaitBackgroundTasks!({
1108
+ providerThread: thread,
1109
+ taskIds: [shellID],
1110
+ awaited: true,
1111
+ }),
1112
+ { matched: [] },
1113
+ );
1114
assert.deepInclude(items.filter((i) => i.type === "command_execution").at(-1), {
1115
type: "command_execution",
1116
status: stopped ? "interrupted" : stop === "failed" ? "failed" : "completed",
@@ -1076,8 +1129,10 @@ it.layer(McpProviderSessions.layer)("OpenCode2 adapter", (it) => {
1129
"settled",
1130
"exited",
1131
"anchored",
1132
+ "awaited",
1133
] as const)("recovers only owned native shells using %s inventory", (discovery) =>
1134
Effect.gen(function* () {
1135
+ const awaited = discovery === "awaited";
1136
const idAllocator = yield* IdAllocator.IdAllocatorV2.pipe(Effect.provide(IdAllocator.layer));
1137
const id = "sh_recovered";
1138
const info = {
@@ -1158,6 +1213,18 @@ it.layer(McpProviderSessions.layer)("OpenCode2 adapter", (it) => {
1213
shellRecovery: inventory,
1214
external: true,
1215
...(discovery === "anchored" ? { lastRunOrdinal: 7 } : {}),
1216
+ ...(awaited
1217
+ ? {
1218
+ pendingBackgroundTasks: [
1219
+ {
1220
+ taskId: id,
1221
+ kind: "command" as const,
1222
+ description: info.command,
1223
+ awaited: true,
1224
+ },
1225
+ ],
1226
+ }
1227
+ : {}),
1228
replayGate: gate,
1229
},
1230
);
@@ -1183,13 +1250,30 @@ it.layer(McpProviderSessions.layer)("OpenCode2 adapter", (it) => {
1250
);
1251
assert.deepEqual(
1252
thread.pendingBackgroundTasks ?? [],
1186
- discovery === "settled" ? [] : [{ taskId: id, kind: "command", description: info.command }],
1253
+ discovery === "settled"
1254
+ ? []
1255
+ : [
1256
+ {
1257
+ taskId: id,
1258
+ kind: "command",
1259
+ description: info.command,
1260
+ ...(awaited ? { awaited: true } : {}),
1261
+ },
1262
+ ],
1263
);
1264
assert.equal(
1265
yield* runtime.hasPendingBackgroundWorkForThread!(thread),
1266
discovery !== "settled",
1267
);
1268
yield* runtime.stopTask!({ providerThread: thread, taskId: "sh_other" });
1269
+ assert.deepEqual(
1270
+ yield* runtime.awaitBackgroundTasks!({
1271
+ providerThread: thread,
1272
+ taskIds: [id, "sh_other"],
1273
+ awaited: true,
1274
+ }),
1275
+ { matched: discovery === "settled" ? [] : [id] },
1276
+ );
1277
assert.equal(
1278
yield* runtime.hasPendingBackgroundWorkForThread!(thread),
1279
discovery !== "settled",
evals/mcp-tool-use/cases/background-wait.ndjson
new
+2
@@ -0,0 +1,2 @@
1
+{"id":"background-wait-opencode-tests","area":"background-wait","kind":"bad","pattern":"OpenCode awaits a background validation result -> mark only that shell awaited","experience":"OpenCode background shells outlived successful turns without a supported explicit wait marker, so T3 presented validation as finished.","privacy":"commit-safe","setup":{"role":"top","context":"You are running through the OpenCode provider in T3. Two native background shells have already launched: sh_tests runs the requested validation; sh_dev serves the development app and should stay running after the work is done. Their completion notifications will wake you automatically. There is no other work to do until validation ends.","mocks":{"t3_background_wait":{"matched":["sh_tests"],"unmatched":[]}}},"prompt":"Wait for the validation shell sh_tests, then inspect its result when it finishes. Leave sh_dev running. Do not poll or stop either shell.","expect":{"calls":[{"tool":"t3_background_wait","args":{"taskIds":["sh_tests"]}}],"callsMustNot":[{"tool":"t3_background_wait","args":{"taskIds":["sh_dev"]}},{"tool":"t3_background_wait","args":{"waiting":false}}]},"maxSteps":5,"source":{"issue":"https://github.com/pingdotgg/t3code/issues/35214"},"notes":"API replay exercises the provider-neutral tool description with OpenCode context, not an OpenCode harness capture or the adapter's injected instructions."}
2
+{"id":"background-wait-opencode-dev-server","area":"background-wait","kind":"guard","pattern":"intentionally detached OpenCode dev server -> no wait mark","experience":"The old customization kept finished threads in Working merely because their dev servers were still running.","privacy":"commit-safe","setup":{"role":"top","context":"You are running through the OpenCode provider in T3. Validation passed. The only background work is sh_dev, the development server, which is ready at http://localhost:3000. No further agent work depends on its exit."},"prompt":"We're done. Leave the dev server running and give me a short summary. Don't inspect the browser.","expect":{"callsMustNot":[{"tool":"t3_background_wait"}]},"maxSteps":3,"source":{"decision":"https://github.com/pingdotgg/t3code/pull/24610"}}
packages/provider-opencode/src/server/v2/adapter.ts
+31
-1
@@ -965,6 +965,7 @@ export const make = Effect.fn("OpenCode2Adapter.make")(function* (instanceId: Pr
965
tool?: { name: string; input: Record<string, unknown> };
966
command: string;
967
running: boolean;
968
+ awaited?: boolean;
969
stopping?: boolean;
970
output: string;
971
cursor: number;
@@ -1627,6 +1628,7 @@ export const make = Effect.fn("OpenCode2Adapter.make")(function* (instanceId: Pr
1628
taskId,
1629
kind: "command",
1630
description: shell.command,
1631
+ ...(shell.awaited === true ? { awaited: true } : {}),
1632
...(shell.state.subagent === undefined
1633
? {}
1634
: { parentTaskId: shell.state.subagent.call.nativeId }),
@@ -1646,7 +1648,7 @@ export const make = Effect.fn("OpenCode2Adapter.make")(function* (instanceId: Pr
1648
: [],
1649
),
1650
);
1649
- const allTasks = [...roster, ...imageTasks];
1651
+ const allTasks = roster.concat(imageTasks);
1652
const current = state.providerThread.pendingBackgroundTasks ?? [];
1653
if (
1654
state.publishedBackgroundWork === hasBackground(state) &&
@@ -1655,6 +1657,7 @@ export const make = Effect.fn("OpenCode2Adapter.make")(function* (instanceId: Pr
1657
(task, index) =>
1658
task.taskId === allTasks[index]?.taskId &&
1659
task.description === allTasks[index]?.description &&
1660
+ task.awaited === allTasks[index]?.awaited &&
1661
(task.kind === "subagent" ? task.childThreadId : undefined) ===
1662
(allTasks[index]?.kind === "subagent" ? allTasks[index]?.childThreadId : undefined),
1663
)
@@ -1844,6 +1847,10 @@ export const make = Effect.fn("OpenCode2Adapter.make")(function* (instanceId: Pr
1847
tool: { name: "shell", input: { command: info.command } },
1848
}),
1849
command: info.command,
1850
+ awaited:
1851
+ state.providerThread.pendingBackgroundTasks?.some(
1852
+ (task) => task.taskId === info.id && task.awaited === true,
1853
+ ) === true,
1854
running: true,
1855
output: "",
1856
cursor: 0,
@@ -4226,6 +4233,9 @@ export const make = Effect.fn("OpenCode2Adapter.make")(function* (instanceId: Pr
4233
const instructions = [
4234
buildRuntimeInstructions({ harness: "OpenCode", model: turnInput.modelSelection.model }),
4235
t3OrchestrationSystemPrompt(mcpAvailable, mcpSession?.capabilities?.has("device") === true),
4236
+ mcpAvailable
4237
+ ? "To wait for a background shell you started (tests, a build), call `t3_background_wait` with its shell ID before you end your turn. Do not mark work you leave running, or PRs."
4238
+ : undefined,
4239
]
4240
.filter((part) => part !== undefined && part.length > 0)
4241
.join("\n\n");
@@ -5013,6 +5023,26 @@ export const make = Effect.fn("OpenCode2Adapter.make")(function* (instanceId: Pr
5023
),
5024
),
5025
),
5026
+ awaitBackgroundTasks: Effect.fn("OpenCode2Adapter.awaitBackgroundTasks")(
5027
+ function* ({ providerThread, taskIds, awaited }) {
5028
+ const nativeThreadId = providerThread.nativeThreadRef?.nativeId;
5029
+ const state = nativeThreadId == null ? undefined : threads.get(nativeThreadId);
5030
+ if (state === undefined) return { matched: [] };
5031
+ const sessions = sessionsOf(state);
5032
+ const matched = [...new Set(taskIds)].filter((taskId) => {
5033
+ const shell = shells.get(taskId);
5034
+ return shell !== undefined && shell.running && sessions.includes(shell.state);
5035
+ });
5036
+ if (matched.length === 0) return { matched };
5037
+ for (const taskId of matched) {
5038
+ const shell = shells.get(taskId)!;
5039
+ shell.awaited = awaited;
5040
+ yield* syncRosterAncestors(shell.state);
5041
+ }
5042
+ return { matched };
5043
+ },
5044
+ (effect) => effect.pipe(lock.withPermit),
5045
+ ),
5046
stopTask: Effect.fn("OpenCode2Adapter.stopTask")(function* ({ providerThread, taskId }) {
5047
const shell = shells.get(taskId);
5048
const state =