From 2de8f02ce96a48c841bacf7ae2d739f2e0060b0b Mon Sep 17 00:00:00 2001 From: Mandeep <97558331+khairm@users.noreply.github.com> Date: Tue, 10 Nov 2026 16:26:16 +0000 Subject: [PATCH 1/4] fix(server): a subagent's own background commands keep the thread working When a Claude subagent ends its turn while its own background Bash still runs, Claude reports the subagent completed. The shell stays in the pending background roster with parentTaskId, but the hold check ignored that field, so the thread left Working while the subagent's work ran. Count any task with a parentTaskId as holding completion. Fixes #27700 Co-Authored-By: Claude Opus 5.5 --- .../Adapters/ClaudeAdapterV2.test.ts | 18 ++++++++++++++++++ docs/user/thread-sidebar.md | 8 ++++---- ...rchestrationV2PendingBackgroundWork.test.ts | 5 +++++ .../orchestrationV2PendingBackgroundWork.ts | 12 ++++++++---- 4 files changed, 35 insertions(+), 8 deletions(-) diff --git a/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts b/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts index d7d03c779b4bb..2f46991f85dfa 100644 --- a/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts +++ b/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts @@ -75,6 +75,7 @@ import * as TestClock from "effect/testing/TestClock"; import { Tool } from "effect/ai"; import { formatClaudeResumeCompactionQuestion } from "@t3tools/shared/claudeCompaction"; import * as HostProcess from "@t3tools/shared/HostProcess"; +import { backgroundWorkHoldsCompletion } from "@t3tools/shared/orchestrationV2PendingBackgroundWork"; import { getModelSelectionStringOptionValue } from "@t3tools/shared/model"; import { SpawnExecutableResolution } from "@t3tools/shared/shell"; @@ -9944,6 +9945,23 @@ describe("ClaudeAdapterV2 background wake turns", () => { event.providerThread.pendingBackgroundTasks?.[0]?.parentTaskId === "agent-1", ), ); + // The helper ends its turn while its shell runs; the shell still holds the thread. + yield* harness.offerAndWait( + makeSubagentNotificationFrame({ + taskId: "agent-1", + toolUseId: "toolu_agent_1", + summary: "Agent is waiting on its own background work.", + uuid: "00000000-0000-4000-8000-000000000204", + }), + ); + const helperShell = + providerThreadRosterEvents(harness.events).at(-1)?.providerThread + .pendingBackgroundTasks ?? []; + assert.deepStrictEqual( + helperShell.map((task) => task.taskId), + ["subagent-shell"], + ); + assert.isTrue(backgroundWorkHoldsCompletion(helperShell)); yield* Queue.offer(harness.sdkMessages, emptyRoster); yield* harness.until(() => diff --git a/docs/user/thread-sidebar.md b/docs/user/thread-sidebar.md index 8de252f90c35e..bd6dabb2baf74 100644 --- a/docs/user/thread-sidebar.md +++ b/docs/user/thread-sidebar.md @@ -135,10 +135,10 @@ open. Threads that are working or waiting on work they will resume from move into a collapsed **Working** section below the active list. -That includes subagents, watched pull requests, and background commands or monitors the agent -says it is waiting on. A dev server or other process an agent leaves running does not keep a thread -there. A thread returns to the top of the active list when it finishes, fails, or needs an approval or -answer. The Working section lists the thread you last sent work to first. Pinned threads stay in +That includes subagents and any commands they leave running, watched pull requests, and background +commands or monitors the agent says it is waiting on. A dev server or other process the thread's own +agent leaves running does not keep a thread there. A thread returns to the top of the active list +when it finishes, fails, or needs an approval or answer. The Working section lists the thread you last sent work to first. Pinned threads stay in the pinned section. This is on by default. Turn it off with **Settings → General → Working section** on web and desktop, diff --git a/packages/shared/src/orchestrationV2PendingBackgroundWork.test.ts b/packages/shared/src/orchestrationV2PendingBackgroundWork.test.ts index 1b5331c0d1bed..400efcac5ace0 100644 --- a/packages/shared/src/orchestrationV2PendingBackgroundWork.test.ts +++ b/packages/shared/src/orchestrationV2PendingBackgroundWork.test.ts @@ -11,6 +11,11 @@ describe("backgroundWorkHoldsCompletion", () => { ["a dev server's watchdog monitor", false, [{ taskId: "watch", kind: "monitor" }]], ["a command the agent waits on", true, [{ taskId: "tests", kind: "command", awaited: true }]], ["a subagent", true, [{ taskId: "review", kind: "subagent" }]], + [ + "a subagent's own command", + true, + [{ taskId: "tests", kind: "command", parentTaskId: "review" }], + ], ] as const)("with %s pending, holds completion: %s", (_case, holds, tasks) => { expect(backgroundWorkHoldsCompletion(tasks)).toBe(holds); }); diff --git a/packages/shared/src/orchestrationV2PendingBackgroundWork.ts b/packages/shared/src/orchestrationV2PendingBackgroundWork.ts index 6dc635b5153a6..4d6a7b8232b57 100644 --- a/packages/shared/src/orchestrationV2PendingBackgroundWork.ts +++ b/packages/shared/src/orchestrationV2PendingBackgroundWork.ts @@ -87,15 +87,19 @@ export function deriveBlockedOnThreadWait(input: { } export function backgroundWorkHoldsCompletion( - tasks: ReadonlyArray>, + tasks: ReadonlyArray>, ): boolean { return tasks.some( - (task) => task.awaited === true || backgroundWorkKindHoldsCompletion(task.kind), + (task) => + task.awaited === true || + // A subagent that ends its turn on its own background work is still working. + task.parentTaskId !== undefined || + backgroundWorkKindHoldsCompletion(task.kind), ); } -// Commands and monitors are as often a dev server or its watchdog as a wait, so they hold -// only when the agent marks them awaited. +// A thread's own commands and monitors are as often a dev server or its watchdog as a wait, +// so they hold only when the agent marks them awaited. function backgroundWorkKindHoldsCompletion(kind: PendingBackgroundWorkTask["kind"]): boolean { switch (kind) { case "command": From 4cd36820e9af046b3893f5e7d1fcc2d3bebaccea Mon Sep 17 00:00:00 2001 From: Mandeep <97558331+khairm@users.noreply.github.com> Date: Tue, 10 Nov 2026 16:30:18 +0000 Subject: [PATCH 2/4] fork:helper-background-hold: markers, features list, version 434001 Carries pingdotgg/t3code#33959 on the fork until upstream ships it. Co-Authored-By: Claude Opus 5.5 --- .fork/features.txt | 4 ++++ .fork/version.txt | 2 +- AGENTS.md | 2 +- .../src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts | 3 ++- docs/user/thread-sidebar.md | 1 + .../shared/src/orchestrationV2PendingBackgroundWork.test.ts | 1 + packages/shared/src/orchestrationV2PendingBackgroundWork.ts | 3 ++- 7 files changed, 12 insertions(+), 4 deletions(-) diff --git a/.fork/features.txt b/.fork/features.txt index 2b8f479800f9e..c259cae4a8ceb 100644 --- a/.fork/features.txt +++ b/.fork/features.txt @@ -1,3 +1,7 @@ # . The marker must stay in its file, and only these files may differ from upstream. fork:paired-session-ttl apps/server/src/auth/EnvironmentAuth.ts fork:paired-session-ttl apps/server/src/auth/EnvironmentAuth.test.ts +fork:helper-background-hold packages/shared/src/orchestrationV2PendingBackgroundWork.ts +fork:helper-background-hold packages/shared/src/orchestrationV2PendingBackgroundWork.test.ts +fork:helper-background-hold apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts +fork:helper-background-hold docs/user/thread-sidebar.md diff --git a/.fork/version.txt b/.fork/version.txt index 2063c47a7c1a4..bebeebc8bb24f 100644 --- a/.fork/version.txt +++ b/.fork/version.txt @@ -1 +1 @@ -0.1.8-nightly.20261107.434000 +0.1.8-nightly.20261107.434001 diff --git a/AGENTS.md b/AGENTS.md index fa47098687121..0f92755eb9ff7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ Fork of pingdotgg/t3code for the owner's NixOS server and Windows ARM64 PC. Upst - Flow: the server's `t3-fork-sync` (khairm/Self-Hosted) merges each new upstream nightly into `candidate/`, gates and builds it, dispatches `fork-desktop.yml` for a draft release, then fast-forwards `main`. Self-Hosted pins `main`'s commit. The server publishes the draft, which creates tag `v`, only once it runs that version, so the PC never runs ahead of it. - Allowed files: `git diff --name-only refs/upstream-tags/ HEAD` may list only `.fork/*`, `AGENTS.md`, `.github/workflows/fork-desktop.yml`, deleted upstream workflows (all but `release-desktop.yml`) and the files in `.fork/features.txt`. Everything else equals upstream, so the official phone app keeps working. -- Source changes: only `fork:paired-session-ttl` (owner-approved): a bearer session redeemed from a one-time pairing code (subject `one-time-token`, no DPoP) lasts 10 years, so devices pair once. Every other session keeps upstream's lifetime. +- Source changes (owner-approved): `fork:paired-session-ttl`: a bearer session redeemed from a one-time pairing code (subject `one-time-token`, no DPoP) lasts 10 years, so devices pair once. Every other session keeps upstream's lifetime. `fork:helper-background-hold` (upstream PR pingdotgg/t3code#33959): a Claude subagent's own background commands keep the thread Working after the subagent ends its turn; drop it once upstream ships it. - Features: each `.fork/features.txt` line is ` `. The marker must survive every merge. Adding a feature is a reviewed PR that adds its line. - Version: `.fork/version.txt` is `-nightly..`, k=00 for an upstream merge and 01-99 for fork-only rebuilds. It rises with every release. `.fork/upstream-baseline.txt` names the merged upstream tag. - Humans branch, then PR into `main`. Never push upstream tags here. The server publishes drafts. diff --git a/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts b/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts index 2f46991f85dfa..5096d8f12cd4d 100644 --- a/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts +++ b/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts @@ -9945,7 +9945,8 @@ describe("ClaudeAdapterV2 background wake turns", () => { event.providerThread.pendingBackgroundTasks?.[0]?.parentTaskId === "agent-1", ), ); - // The helper ends its turn while its shell runs; the shell still holds the thread. + // fork:helper-background-hold: the helper ends its turn while its shell runs; the + // shell still holds the thread. yield* harness.offerAndWait( makeSubagentNotificationFrame({ taskId: "agent-1", diff --git a/docs/user/thread-sidebar.md b/docs/user/thread-sidebar.md index bd6dabb2baf74..01d1cc2baf9a2 100644 --- a/docs/user/thread-sidebar.md +++ b/docs/user/thread-sidebar.md @@ -135,6 +135,7 @@ open. Threads that are working or waiting on work they will resume from move into a collapsed **Working** section below the active list. + That includes subagents and any commands they leave running, watched pull requests, and background commands or monitors the agent says it is waiting on. A dev server or other process the thread's own agent leaves running does not keep a thread there. A thread returns to the top of the active list diff --git a/packages/shared/src/orchestrationV2PendingBackgroundWork.test.ts b/packages/shared/src/orchestrationV2PendingBackgroundWork.test.ts index 400efcac5ace0..e6a38fe43ade7 100644 --- a/packages/shared/src/orchestrationV2PendingBackgroundWork.test.ts +++ b/packages/shared/src/orchestrationV2PendingBackgroundWork.test.ts @@ -12,6 +12,7 @@ describe("backgroundWorkHoldsCompletion", () => { ["a command the agent waits on", true, [{ taskId: "tests", kind: "command", awaited: true }]], ["a subagent", true, [{ taskId: "review", kind: "subagent" }]], [ + // fork:helper-background-hold "a subagent's own command", true, [{ taskId: "tests", kind: "command", parentTaskId: "review" }], diff --git a/packages/shared/src/orchestrationV2PendingBackgroundWork.ts b/packages/shared/src/orchestrationV2PendingBackgroundWork.ts index 4d6a7b8232b57..c9f3b7e5534cb 100644 --- a/packages/shared/src/orchestrationV2PendingBackgroundWork.ts +++ b/packages/shared/src/orchestrationV2PendingBackgroundWork.ts @@ -92,7 +92,8 @@ export function backgroundWorkHoldsCompletion( return tasks.some( (task) => task.awaited === true || - // A subagent that ends its turn on its own background work is still working. + // fork:helper-background-hold: a subagent that ends its turn on its own background + // work is still working. task.parentTaskId !== undefined || backgroundWorkKindHoldsCompletion(task.kind), ); From 303aba964cb8ee28bad20dad4ca48c7497594f58 Mon Sep 17 00:00:00 2001 From: Mandeep <97558331+khairm@users.noreply.github.com> Date: Tue, 10 Nov 2026 16:39:32 +0000 Subject: [PATCH 3/4] fork:helper-background-hold: doc marker above the section, rewrap paragraph Co-Authored-By: Claude Opus 5.5 --- docs/user/thread-sidebar.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/user/thread-sidebar.md b/docs/user/thread-sidebar.md index 01d1cc2baf9a2..b80128e140aac 100644 --- a/docs/user/thread-sidebar.md +++ b/docs/user/thread-sidebar.md @@ -131,16 +131,17 @@ rename a thread, regenerate its title, or link and unlink a pull request. These appear on web, desktop, and mobile without requiring the originating browser to remain open. + + ### Fold working threads (beta) Threads that are working or waiting on work they will resume from move into a collapsed **Working** section below the active list. - That includes subagents and any commands they leave running, watched pull requests, and background commands or monitors the agent says it is waiting on. A dev server or other process the thread's own agent leaves running does not keep a thread there. A thread returns to the top of the active list -when it finishes, fails, or needs an approval or answer. The Working section lists the thread you last sent work to first. Pinned threads stay in -the pinned section. +when it finishes, fails, or needs an approval or answer. The Working section lists the thread you +last sent work to first. Pinned threads stay in the pinned section. This is on by default. Turn it off with **Settings → General → Working section** on web and desktop, or **Settings → General → Working section** on iOS and Android. Each device keeps its own From 31aef69b4ff252905769a2e93608e5e06d2746e9 Mon Sep 17 00:00:00 2001 From: Mandeep Date: Tue, 10 Nov 2026 17:10:00 +0000 Subject: [PATCH 4/4] fork:helper-background-hold: act out a finished helper's command lifecycle Carries the upstream test change from pingdotgg/t3code#33959: a helper starts, its own local_bash task starts with parent_task_id, the helper reports completed, and the command still holds the thread until its own task_notification. AGENTS.md notes the full trade-off. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 2 +- .../Adapters/ClaudeAdapterV2.test.ts | 121 +++++++++++++++--- 2 files changed, 104 insertions(+), 19 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 0f92755eb9ff7..da41eb15aa46b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ Fork of pingdotgg/t3code for the owner's NixOS server and Windows ARM64 PC. Upst - Flow: the server's `t3-fork-sync` (khairm/Self-Hosted) merges each new upstream nightly into `candidate/`, gates and builds it, dispatches `fork-desktop.yml` for a draft release, then fast-forwards `main`. Self-Hosted pins `main`'s commit. The server publishes the draft, which creates tag `v`, only once it runs that version, so the PC never runs ahead of it. - Allowed files: `git diff --name-only refs/upstream-tags/ HEAD` may list only `.fork/*`, `AGENTS.md`, `.github/workflows/fork-desktop.yml`, deleted upstream workflows (all but `release-desktop.yml`) and the files in `.fork/features.txt`. Everything else equals upstream, so the official phone app keeps working. -- Source changes (owner-approved): `fork:paired-session-ttl`: a bearer session redeemed from a one-time pairing code (subject `one-time-token`, no DPoP) lasts 10 years, so devices pair once. Every other session keeps upstream's lifetime. `fork:helper-background-hold` (upstream PR pingdotgg/t3code#33959): a Claude subagent's own background commands keep the thread Working after the subagent ends its turn; drop it once upstream ships it. +- Source changes (owner-approved): `fork:paired-session-ttl`: a bearer session redeemed from a one-time pairing code (subject `one-time-token`, no DPoP) lasts 10 years, so devices pair once. Every other session keeps upstream's lifetime. `fork:helper-background-hold` (upstream PR pingdotgg/t3code#33959): a Claude subagent's own background commands keep the thread Working after the subagent ends its turn. Trade-off: a helper-started dev server also holds the sidebar, `delegatedTaskProgress` and delegated `wait` results until it exits or Stop; the upstream phone app computes the hold itself, so it keeps the old behaviour. Drop it once upstream ships it. - Features: each `.fork/features.txt` line is ` `. The marker must survive every merge. Adding a feature is a reviewed PR that adds its line. - Version: `.fork/version.txt` is `-nightly..`, k=00 for an upstream merge and 01-99 for fork-only rebuilds. It rises with every release. `.fork/upstream-baseline.txt` names the merged upstream tag. - Humans branch, then PR into `main`. Never push upstream tags here. The server publishes drafts. diff --git a/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts b/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts index 5096d8f12cd4d..21e1b77967fcf 100644 --- a/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts +++ b/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts @@ -9945,24 +9945,6 @@ describe("ClaudeAdapterV2 background wake turns", () => { event.providerThread.pendingBackgroundTasks?.[0]?.parentTaskId === "agent-1", ), ); - // fork:helper-background-hold: the helper ends its turn while its shell runs; the - // shell still holds the thread. - yield* harness.offerAndWait( - makeSubagentNotificationFrame({ - taskId: "agent-1", - toolUseId: "toolu_agent_1", - summary: "Agent is waiting on its own background work.", - uuid: "00000000-0000-4000-8000-000000000204", - }), - ); - const helperShell = - providerThreadRosterEvents(harness.events).at(-1)?.providerThread - .pendingBackgroundTasks ?? []; - assert.deepStrictEqual( - helperShell.map((task) => task.taskId), - ["subagent-shell"], - ); - assert.isTrue(backgroundWorkHoldsCompletion(helperShell)); yield* Queue.offer(harness.sdkMessages, emptyRoster); yield* harness.until(() => @@ -9986,6 +9968,109 @@ describe("ClaudeAdapterV2 background wake turns", () => { ), ); + it.effect("keeps a finished helper's own background command pending until it ends", () => + Effect.scoped( + Effect.gen(function* () { + const harness = yield* makeWakeHarness; + const now = yield* DateTime.now; + const latestRoster = () => + providerThreadRosterEvents(harness.events).at(-1)?.providerThread + .pendingBackgroundTasks ?? []; + yield* harness.runtime.startTurn( + makeClaudeTestTurnInput({ + threadId: harness.threadId, + providerThread: harness.providerThread, + now, + attemptId: RunAttemptId.make("attempt-claude-helper-shell"), + text: "Start the dev server from a helper.", + attachments: [], + }), + ); + yield* Queue.offer( + harness.sdkMessages, + makeSubagentTaskStartedFrame({ + taskId: "helper", + toolUseId: "toolu_helper", + uuid: "00000000-0000-4000-8000-000000000211", + }), + ); + yield* Queue.offer( + harness.sdkMessages, + makeResultFrame({ + uuid: "00000000-0000-4000-8000-000000000212", + result: "A helper is starting the dev server.", + }), + ); + yield* harness.awaitTerminal(1); + + yield* Queue.offer( + harness.sdkMessages, + claudeSdkFrame({ + type: "system", + subtype: "task_started", + task_id: "helper-shell", + tool_use_id: "toolu_helper_shell", + description: "npm run dev", + is_backgrounded: true, + task_type: "local_bash", + parent_task_id: "helper", + uuid: "00000000-0000-4000-8000-000000000213", + session_id: WAKE_NATIVE_SESSION, + }), + ); + yield* harness.until(() => latestRoster()[0]?.parentTaskId === "helper"); + // fork:helper-background-hold: the helper ends its turn while its command runs; the + // command still holds the thread. + yield* harness.offerAndWait( + makeSubagentNotificationFrame({ + taskId: "helper", + toolUseId: "toolu_helper", + summary: "The dev server is running.", + uuid: "00000000-0000-4000-8000-000000000214", + }), + ); + yield* harness.until(() => + harness.events.some( + (event) => event.type === "subagent.updated" && event.subagent.status === "completed", + ), + ); + assert.deepStrictEqual( + latestRoster().map((task) => [task.taskId, task.parentTaskId]), + [["helper-shell", "helper"]], + ); + assert.isTrue(backgroundWorkHoldsCompletion(latestRoster())); + assert.isTrue(yield* harness.hasPendingBackgroundWork); + + yield* Queue.offer( + harness.sdkMessages, + claudeSdkFrame({ + type: "system", + subtype: "task_notification", + task_id: "helper-shell", + tool_use_id: "toolu_helper_shell", + status: "completed", + output_file: "/tmp/helper-shell.output", + summary: "npm run dev exited.", + uuid: "00000000-0000-4000-8000-000000000215", + session_id: WAKE_NATIVE_SESSION, + }), + ); + yield* harness.until(() => latestRoster().length === 0); + assert.isFalse(backgroundWorkHoldsCompletion(latestRoster())); + assert.isFalse(yield* harness.hasPendingBackgroundWork); + }).pipe( + Effect.provide( + Layer.mergeAll( + IdAllocator.layer, + McpProviderSessions.layer, + NodeServices.layer, + NodeCrypto.layer, + ), + ), + ), + ), + ); + it.effect("holds only the background tasks the agent marks awaited, until they end", () => Effect.scoped( Effect.gen(function* () {