From 7db8c758be982070ba1ac9c1bf16194a39937615 Mon Sep 17 00:00:00 2001 From: Omar <76748259+omar9848492@users.noreply.github.com> Date: Tue, 17 Nov 2026 11:06:05 -0500 Subject: [PATCH] feat(server): background commands can hold their thread in Working by default With T3CODE_BACKGROUND_COMMANDS_HOLD=1, a Claude background command counts as awaited unless the agent releases it with t3_background_wait waiting:false (a dev server, a watcher). A thread whose agent waits on a deploy or CI command then stays in Working as Waiting, matching its "Waiting on 1 command" footer, even when the agent never marked it. Off by default; upstream behaviour is unchanged. Co-Authored-By: Claude Opus 5.5 --- .../Adapters/ClaudeAdapterV2.test.ts | 77 +++++++++++++++++++ .../Adapters/ClaudeAdapterV2.ts | 37 ++++++++- 2 files changed, 113 insertions(+), 1 deletion(-) diff --git a/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts b/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts index d0dda62b1ff20..8153ce764811d 100644 --- a/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts +++ b/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts @@ -12582,6 +12582,83 @@ describe("ClaudeAdapterV2 background wake turns", () => { ), ); + it.effect("holds background commands by default when T3CODE_BACKGROUND_COMMANDS_HOLD is on", () => + Effect.gen(function* () { + const harness = yield* makeWakeHarnessWithOptions({ + environment: { [ClaudeAdapterV2.CLAUDE_BACKGROUND_COMMANDS_HOLD_ENV]: "1" }, + }); + const now = yield* DateTime.now; + const awaitBackgroundTasks = harness.runtime.awaitBackgroundTasks; + if (awaitBackgroundTasks === undefined) { + throw new Error("Claude adapter runtime must expose awaitBackgroundTasks."); + } + const nextRoster = Effect.fn("nextRoster")(function* ( + matches: (tasks: ReadonlyArray) => boolean, + ) { + while (true) { + const { providerThread } = yield* Queue.take(harness.providerThreadReceipts); + const tasks = providerThread.pendingBackgroundTasks ?? []; + if (matches(tasks)) return tasks; + } + }); + const marks = (tasks: ReadonlyArray) => + tasks.map((task) => [task.taskId, task.awaited === true]); + yield* harness.runtime.startTurn( + makeClaudeTestTurnInput({ + threadId: harness.threadId, + providerThread: harness.providerThread, + now, + attemptId: RunAttemptId.make("attempt-claude-commands-hold"), + text: "Wait for the deploy in the background and start the dev server.", + attachments: [], + }), + ); + yield* Queue.offer( + harness.sdkMessages, + claudeSdkFrame({ + type: "system", + subtype: "background_tasks_changed", + tasks: ["deploy-wait", "dev-server"].map((taskId) => ({ + task_id: taskId, + task_type: "local_bash", + description: taskId, + })), + uuid: "00000000-0000-4000-8000-000000000351", + session_id: WAKE_NATIVE_SESSION, + }), + ); + // Unmarked commands hold the thread without a t3_background_wait call. + assert.deepStrictEqual(marks(yield* nextRoster((tasks) => tasks.length === 2)), [ + ["deploy-wait", true], + ["dev-server", true], + ]); + // The agent releases a dev server explicitly. + yield* awaitBackgroundTasks({ + providerThread: harness.providerThread, + taskIds: ["dev-server"], + awaited: false, + }); + assert.deepStrictEqual( + marks(yield* nextRoster((tasks) => tasks.some((task) => task.awaited !== true))), + [ + ["deploy-wait", true], + ["dev-server", false], + ], + ); + yield* Queue.offer(harness.sdkMessages, turnOneResult); + yield* Queue.take(harness.terminalReceipts); + }).pipe( + Effect.provide( + Layer.mergeAll( + IdAllocator.layer, + McpProviderSessions.layer, + NodeServices.layer, + NodeCrypto.layer, + ), + ), + ), + ); + it.effect("keeps a running Claude monitor typed after many newer monitors end", () => Effect.gen(function* () { const harness = yield* makeWakeHarness; diff --git a/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts b/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts index edb8ef01301a9..16ee71d6d844e 100644 --- a/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts +++ b/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts @@ -3756,6 +3756,8 @@ function isClaudeLocalCommandEcho(message: SDKMessage): boolean { return typeof content === "string" && content.startsWith(""); } +export const CLAUDE_BACKGROUND_COMMANDS_HOLD_ENV = "T3CODE_BACKGROUND_COMMANDS_HOLD"; + function claudePendingBackgroundTasksFromRoster( roster: ReadonlyMap, awaitedTaskIds: ReadonlySet, @@ -5918,6 +5920,11 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* ( const awaitedBackgroundTasksByNativeThread = yield* Ref.make( new Map>(), ); + // Opt-in: a background command holds its thread like an awaited one until the agent + // releases it with t3_background_wait waiting:false (a dev server, a watcher). + const backgroundCommandsHold = + adapterOptions.environment[CLAUDE_BACKGROUND_COMMANDS_HOLD_ENV] === "1"; + const releasedBackgroundTasksByNativeThread = new Map>(); // Wake eligibility is separate from the Waiting roster. It survives empty // background_tasks_changed levels (SDK: empty level can precede task_notification) and // is consumed when the first idle notification is buffered/offered so duplicates cannot @@ -6119,7 +6126,26 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* ( roster: ReadonlyMap, awaitedTaskIds: ReadonlySet, ): ReadonlyArray => { - const tasks = claudePendingBackgroundTasksFromRoster(roster, awaitedTaskIds); + const released = + nativeThreadId === null + ? undefined + : releasedBackgroundTasksByNativeThread.get(nativeThreadId); + if (released !== undefined) { + for (const taskId of released) if (!roster.has(taskId)) released.delete(taskId); + } + const tasks = claudePendingBackgroundTasksFromRoster( + roster, + backgroundCommandsHold + ? new Set([ + ...awaitedTaskIds, + ...Array.from(roster.values()) + .filter( + (task) => task.kind === "command" && released?.has(task.taskId) !== true, + ) + .map((task) => task.taskId), + ]) + : awaitedTaskIds, + ); return nativeThreadId !== null && scheduledWakeupsByNativeThread.has(nativeThreadId) ? [...tasks, CLAUDE_SCHEDULED_WAKEUP_TASK] : tasks; @@ -14233,6 +14259,15 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* ( ); const matched = [...new Set(taskIds)].filter((taskId) => roster.has(taskId)); if (matched.length === 0) return { matched }; + const released = + releasedBackgroundTasksByNativeThread.get(nativeThreadId) ?? new Set(); + for (const taskId of matched) { + if (awaited) released.delete(taskId); + else released.add(taskId); + } + if (released.size > 0) + releasedBackgroundTasksByNativeThread.set(nativeThreadId, released); + else releasedBackgroundTasksByNativeThread.delete(nativeThreadId); if (awaited) { yield* addTaskIdsToNativeThreadSet( awaitedBackgroundTasksByNativeThread,