From b4ea02b0a8245ca94b5fcfc35ae39209f089159a Mon Sep 17 00:00:00 2001 From: Andrei Shenets Date: Thu, 12 Nov 2026 14:09:22 +0100 Subject: [PATCH 1/3] fix(opencode): support explicit background waits --- .../src/mcp/toolkits/orchestrator/tools.ts | 2 +- .../Adapters/OpenCode2AdapterV2.test.ts | 65 +++++++++++++++++++ .../src/provider/agentContextBudget.json | 2 +- .../mcp-tool-use/cases/background-wait.ndjson | 2 + .../src/server/v2/adapter.ts | 32 ++++++++- 5 files changed, 100 insertions(+), 3 deletions(-) create mode 100644 evals/mcp-tool-use/cases/background-wait.ndjson diff --git a/apps/server/src/mcp/toolkits/orchestrator/tools.ts b/apps/server/src/mcp/toolkits/orchestrator/tools.ts index 38d8fb4e0ada5..b1692658dd583 100644 --- a/apps/server/src/mcp/toolkits/orchestrator/tools.ts +++ b/apps/server/src/mcp/toolkits/orchestrator/tools.ts @@ -142,7 +142,7 @@ const WorkflowStopTool = Tool.make("t3_workflow_stop", { const BackgroundWaitTool = Tool.make("t3_background_wait", { description: - "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.", + "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 and OpenCode.", parameters: Schema.Struct({ taskIds: Schema.Array(TrimmedNonEmptyString).check( Schema.isMinLength(1), diff --git a/apps/server/src/orchestration-v2/Adapters/OpenCode2AdapterV2.test.ts b/apps/server/src/orchestration-v2/Adapters/OpenCode2AdapterV2.test.ts index 1efbbfad09d81..af1c582f4e878 100644 --- a/apps/server/src/orchestration-v2/Adapters/OpenCode2AdapterV2.test.ts +++ b/apps/server/src/orchestration-v2/Adapters/OpenCode2AdapterV2.test.ts @@ -994,6 +994,10 @@ it.layer(McpProviderSessions.layer)("OpenCode2 adapter", (it) => { const terminal = yield* runtime.events.pipe( Stream.tap((e) => Effect.gen(function* () { + if (e.type === "provider_thread.updated") { + for (const task of e.providerThread.pendingBackgroundTasks ?? []) + assert.isUndefined(task.awaited); + } if (e.type !== "turn_item.updated") return; items.push(e.turnItem); if (e.turnItem.type === "command_execution" && e.turnItem.output === "retained\n") @@ -1011,6 +1015,51 @@ it.layer(McpProviderSessions.layer)("OpenCode2 adapter", (it) => { } yield* Fiber.join(terminal); assert.isTrue(yield* runtime.hasPendingBackgroundWorkForThread!(thread)); + for (const awaited of [true, false, true]) { + const roster = yield* runtime.events.pipe( + Stream.filter( + (e) => + e.type === "provider_thread.updated" && + e.providerThread.pendingBackgroundTasks?.some( + (task) => task.taskId === shellID && (task.awaited === true) === awaited, + ) === true, + ), + Stream.runHead, + Effect.forkScoped, + ); + assert.deepEqual( + yield* runtime.awaitBackgroundTasks!({ + providerThread: thread, + taskIds: [shellID, "sh_unknown"], + awaited, + }), + { matched: [shellID] }, + ); + yield* Fiber.join(roster); + } + assert.deepEqual( + yield* runtime.awaitBackgroundTasks!({ + providerThread: { + ...thread, + nativeThreadRef: { + driver: OPENCODE_PROVIDER, + nativeId: "ses_foreign", + strength: "strong", + }, + }, + taskIds: [shellID], + awaited: false, + }), + { matched: [] }, + ); + assert.deepEqual( + yield* runtime.awaitBackgroundTasks!({ + providerThread: { ...thread, appThreadId: ThreadId.make("thread:foreign") }, + taskIds: [shellID], + awaited: false, + }), + { matched: [] }, + ); const settled = yield* runtime.events.pipe( Stream.tap((e) => Effect.sync(() => { @@ -1035,6 +1084,14 @@ it.layer(McpProviderSessions.layer)("OpenCode2 adapter", (it) => { else gate.release("shell-exit"); yield* Fiber.join(settled); assert.isFalse(yield* runtime.hasPendingBackgroundWorkForThread!(thread)); + assert.deepEqual( + yield* runtime.awaitBackgroundTasks!({ + providerThread: thread, + taskIds: [shellID], + awaited: true, + }), + { matched: [] }, + ); assert.deepInclude(items.filter((i) => i.type === "command_execution").at(-1), { type: "command_execution", status: stopped ? "interrupted" : stop === "failed" ? "failed" : "completed", @@ -1167,6 +1224,14 @@ it.layer(McpProviderSessions.layer)("OpenCode2 adapter", (it) => { discovery !== "settled", ); yield* runtime.stopTask!({ providerThread: thread, taskId: "sh_other" }); + assert.deepEqual( + yield* runtime.awaitBackgroundTasks!({ + providerThread: thread, + taskIds: [id, "sh_other"], + awaited: true, + }), + { matched: discovery === "settled" ? [] : [id] }, + ); assert.equal( yield* runtime.hasPendingBackgroundWorkForThread!(thread), discovery !== "settled", diff --git a/apps/server/src/provider/agentContextBudget.json b/apps/server/src/provider/agentContextBudget.json index e166af3f78340..89632327bf9f1 100644 --- a/apps/server/src/provider/agentContextBudget.json +++ b/apps/server/src/provider/agentContextBudget.json @@ -1,5 +1,5 @@ { "claudeSystemAppendBytes": 5597, "codexAdditionalContextBytes": 7327, - "mcpToolListJsonBytes": 48126 + "mcpToolListJsonBytes": 48134 } diff --git a/evals/mcp-tool-use/cases/background-wait.ndjson b/evals/mcp-tool-use/cases/background-wait.ndjson new file mode 100644 index 0000000000000..f6fcebc9325bb --- /dev/null +++ b/evals/mcp-tool-use/cases/background-wait.ndjson @@ -0,0 +1,2 @@ +{"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."} +{"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"}} diff --git a/packages/provider-opencode/src/server/v2/adapter.ts b/packages/provider-opencode/src/server/v2/adapter.ts index b13f6c361bacf..f5adaa1b45073 100644 --- a/packages/provider-opencode/src/server/v2/adapter.ts +++ b/packages/provider-opencode/src/server/v2/adapter.ts @@ -909,6 +909,7 @@ export const make = Effect.fn("OpenCode2Adapter.make")(function* (instanceId: Pr tool?: { name: string; input: Record }; command: string; running: boolean; + awaited?: boolean; stopping?: boolean; output: string; cursor: number; @@ -1569,6 +1570,7 @@ export const make = Effect.fn("OpenCode2Adapter.make")(function* (instanceId: Pr taskId, kind: "command", description: shell.command, + ...(shell.awaited === true ? { awaited: true } : {}), ...(shell.state.subagent === undefined ? {} : { parentTaskId: shell.state.subagent.call.nativeId }), @@ -1588,7 +1590,7 @@ export const make = Effect.fn("OpenCode2Adapter.make")(function* (instanceId: Pr : [], ), ); - const allTasks = [...roster, ...imageTasks]; + const allTasks = roster.concat(imageTasks); const current = state.providerThread.pendingBackgroundTasks ?? []; if ( state.publishedBackgroundWork === hasBackground(state) && @@ -1597,6 +1599,7 @@ export const make = Effect.fn("OpenCode2Adapter.make")(function* (instanceId: Pr (task, index) => task.taskId === allTasks[index]?.taskId && task.description === allTasks[index]?.description && + task.awaited === allTasks[index]?.awaited && (task.kind === "subagent" ? task.childThreadId : undefined) === (allTasks[index]?.kind === "subagent" ? allTasks[index]?.childThreadId : undefined), ) @@ -4091,6 +4094,9 @@ export const make = Effect.fn("OpenCode2Adapter.make")(function* (instanceId: Pr const instructions = [ buildRuntimeInstructions({ harness: "OpenCode", model: turnInput.modelSelection.model }), t3OrchestrationSystemPrompt(mcpAvailable, mcpSession?.capabilities?.has("device") === true), + mcpAvailable + ? "Before ending your turn to wait for a background shell (tests, a build), call `t3_background_wait` with its shell ID. Do not mark processes you leave running, such as dev servers or watchers. `waiting: false` clears a wait without stopping the shell. Completion wakes you automatically; do not poll." + : undefined, ] .filter((part) => part !== undefined && part.length > 0) .join("\n\n"); @@ -4861,6 +4867,30 @@ export const make = Effect.fn("OpenCode2Adapter.make")(function* (instanceId: Pr ), ), ), + awaitBackgroundTasks: Effect.fn("OpenCode2Adapter.awaitBackgroundTasks")( + function* ({ providerThread, taskIds, awaited }) { + const nativeId = providerThread.nativeThreadRef?.nativeId; + const state = nativeId == null ? undefined : threads.get(nativeId); + const matched: string[] = []; + if ( + state === undefined || + state.providerThread.id !== providerThread.id || + state.providerThread.appThreadId !== providerThread.appThreadId + ) { + return { matched }; + } + for (const taskId of taskIds) { + const shell = shells.get(taskId); + if (shell === undefined || !shell.running || !sessionsOf(state).includes(shell.state)) + continue; + shell.awaited = awaited; + matched.push(taskId); + yield* syncRosterAncestors(shell.state); + } + return { matched }; + }, + (effect) => effect.pipe(lock.withPermit), + ), stopTask: Effect.fn("OpenCode2Adapter.stopTask")(function* ({ providerThread, taskId }) { const shell = shells.get(taskId); const state = From 637ef420e3d91c64f6cf46b1643d506801839d8f Mon Sep 17 00:00:00 2001 From: Andrei Shenets Date: Thu, 12 Nov 2026 14:19:08 +0100 Subject: [PATCH 2/3] refactor(opencode): align background waits with Claude --- .../Adapters/OpenCode2AdapterV2.test.ts | 10 +------ .../src/server/v2/adapter.ts | 26 ++++++++----------- 2 files changed, 12 insertions(+), 24 deletions(-) diff --git a/apps/server/src/orchestration-v2/Adapters/OpenCode2AdapterV2.test.ts b/apps/server/src/orchestration-v2/Adapters/OpenCode2AdapterV2.test.ts index af1c582f4e878..7544756b525d9 100644 --- a/apps/server/src/orchestration-v2/Adapters/OpenCode2AdapterV2.test.ts +++ b/apps/server/src/orchestration-v2/Adapters/OpenCode2AdapterV2.test.ts @@ -1030,7 +1030,7 @@ it.layer(McpProviderSessions.layer)("OpenCode2 adapter", (it) => { assert.deepEqual( yield* runtime.awaitBackgroundTasks!({ providerThread: thread, - taskIds: [shellID, "sh_unknown"], + taskIds: [shellID, shellID, "sh_unknown"], awaited, }), { matched: [shellID] }, @@ -1052,14 +1052,6 @@ it.layer(McpProviderSessions.layer)("OpenCode2 adapter", (it) => { }), { matched: [] }, ); - assert.deepEqual( - yield* runtime.awaitBackgroundTasks!({ - providerThread: { ...thread, appThreadId: ThreadId.make("thread:foreign") }, - taskIds: [shellID], - awaited: false, - }), - { matched: [] }, - ); const settled = yield* runtime.events.pipe( Stream.tap((e) => Effect.sync(() => { diff --git a/packages/provider-opencode/src/server/v2/adapter.ts b/packages/provider-opencode/src/server/v2/adapter.ts index f5adaa1b45073..5121f4867ff5d 100644 --- a/packages/provider-opencode/src/server/v2/adapter.ts +++ b/packages/provider-opencode/src/server/v2/adapter.ts @@ -4095,7 +4095,7 @@ export const make = Effect.fn("OpenCode2Adapter.make")(function* (instanceId: Pr buildRuntimeInstructions({ harness: "OpenCode", model: turnInput.modelSelection.model }), t3OrchestrationSystemPrompt(mcpAvailable, mcpSession?.capabilities?.has("device") === true), mcpAvailable - ? "Before ending your turn to wait for a background shell (tests, a build), call `t3_background_wait` with its shell ID. Do not mark processes you leave running, such as dev servers or watchers. `waiting: false` clears a wait without stopping the shell. Completion wakes you automatically; do not poll." + ? "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." : undefined, ] .filter((part) => part !== undefined && part.length > 0) @@ -4869,22 +4869,18 @@ export const make = Effect.fn("OpenCode2Adapter.make")(function* (instanceId: Pr ), awaitBackgroundTasks: Effect.fn("OpenCode2Adapter.awaitBackgroundTasks")( function* ({ providerThread, taskIds, awaited }) { - const nativeId = providerThread.nativeThreadRef?.nativeId; - const state = nativeId == null ? undefined : threads.get(nativeId); - const matched: string[] = []; - if ( - state === undefined || - state.providerThread.id !== providerThread.id || - state.providerThread.appThreadId !== providerThread.appThreadId - ) { - return { matched }; - } - for (const taskId of taskIds) { + const nativeThreadId = providerThread.nativeThreadRef?.nativeId; + const state = nativeThreadId == null ? undefined : threads.get(nativeThreadId); + if (state === undefined) return { matched: [] }; + const sessions = sessionsOf(state); + const matched = [...new Set(taskIds)].filter((taskId) => { const shell = shells.get(taskId); - if (shell === undefined || !shell.running || !sessionsOf(state).includes(shell.state)) - continue; + return shell !== undefined && shell.running && sessions.includes(shell.state); + }); + if (matched.length === 0) return { matched }; + for (const taskId of matched) { + const shell = shells.get(taskId)!; shell.awaited = awaited; - matched.push(taskId); yield* syncRosterAncestors(shell.state); } return { matched }; From b5454f024bad064223638ad6f5ff677079146dc7 Mon Sep 17 00:00:00 2001 From: Andrei Shenets Date: Thu, 12 Nov 2026 14:26:56 +0100 Subject: [PATCH 3/3] fix(mcp): preserve background wait support qualifier --- apps/server/src/mcp/toolkits/orchestrator/tools.ts | 2 +- apps/server/src/provider/agentContextBudget.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/apps/server/src/mcp/toolkits/orchestrator/tools.ts b/apps/server/src/mcp/toolkits/orchestrator/tools.ts index b1692658dd583..ca1a79ec7060d 100644 --- a/apps/server/src/mcp/toolkits/orchestrator/tools.ts +++ b/apps/server/src/mcp/toolkits/orchestrator/tools.ts @@ -142,7 +142,7 @@ const WorkflowStopTool = Tool.make("t3_workflow_stop", { const BackgroundWaitTool = Tool.make("t3_background_wait", { description: - "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 and OpenCode.", + "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 and OpenCode only.", parameters: Schema.Struct({ taskIds: Schema.Array(TrimmedNonEmptyString).check( Schema.isMinLength(1), diff --git a/apps/server/src/provider/agentContextBudget.json b/apps/server/src/provider/agentContextBudget.json index 89632327bf9f1..94bd20ca58f8f 100644 --- a/apps/server/src/provider/agentContextBudget.json +++ b/apps/server/src/provider/agentContextBudget.json @@ -1,5 +1,5 @@ { "claudeSystemAppendBytes": 5597, "codexAdditionalContextBytes": 7327, - "mcpToolListJsonBytes": 48134 + "mcpToolListJsonBytes": 48139 }