With the Working section on, threads came back to the inbox while the agent was only waiting on something: tests, benchmarks, CI, a data backfill. In two weeks of real use this happened 121 times, all from Claude background shells, so threads sat in the inbox for about 28 hours in total with nothing to act on. The opposite happened too: a dev server's watchdog Monitor kept a finished thread stuck in Working.
Both came from deciding by task kind. A background shell never held a thread and a monitor always did, but either one can be a wait or a process left running. Only the agent knows which.
t3_background_wait, marks the background commands or Monitors the agent will act on when it is woken. waiting: false clears a mark. IDs that are not running come back in unmatched and change nothing.backgroundWorkHoldsCompletion, marked work, subagents, background tasks, and PR watches hold a thread. Unmarked commands and monitors never do. The same rule drives the Working list on web and mobile, completion alerts, auto-settle, and the restart wake.awaited field.Replaces #22055 by @LovelyCodeMonkey. Their three commits are kept as they were, with authorship, and cherry-picked cleanly onto current main. Added two commits: the restart-recovery doc (docs/internals/server-updates.md) and the shellRuntime comment still described the old rule, and the t3_background_wait description now uses shorter, plainer sentences with the same facts.
Live runs against an isolated dev server (its own state, no copied data), Claude Opus 5.5, with prompts that never mention T3 tools:
| Scenario | t3_background_wait | Roster after the turn | Holds in Working | Then |
|---|---|---|---|---|
sleep 75 && echo 'ALL 42 TESTS PASSED' in the background | called on its own | command, awaited: true | yes | woke on exit, reported the result, came back |
| Monitor on a 3-step deploy | called | monitor, awaited: true | yes | woke on each step, then reported "DEPLOY DONE" |
| Monitor with a 50 s gap between events | called | still awaited: true between wakes | yes | finished |
python3 -m http.server plus an error-watch Monitor, "leave both running" | not called | command and monitor, unmarked | no | back in the inbox right away; main keeps it in Working |
An unplanned server restart during a first attempt also exercised the restart path: the threads with awaited work were woken with the restart note. After the description rewrite, the first and last rows ran again with the same result.
Screenshots from #22055 show the same behavior in the app (other thread titles blurred):
Tests, before (main) | Tests, after, while waiting | Tests, after, with the result |
|---|---|---|
| main: back in the inbox while tests run | branch: in Working while tests run | branch: back with the result |
Dev server, before (main) | Dev server, after |
|---|---|
| main: stuck in Working | branch: back in the inbox |
Tests: vp test run passes for the shared hold rule and awareness, client-runtime presentation, web Sidebar.logic, mobile threadListV2, and the server's Claude adapter, thread management, settlement, restart note and continuation, projection store, delegated completion, runtime layer, awareness relay, and MCP suites. vp run check:changed passes.
Proved with live runs on an isolated dev server plus focused tests.
Reviewed with sol-loop: 1 round with GPT-6.1 Sol on high, before the copy-only description rewrite. Sol verdict: approved
Written by Claude Opus 5.5 in Claude Code, run from T3 Code. Tool description copy by Muse Wonder Full in Muse Code. Original implementation by @LovelyCodeMonkey with Claude Opus 5.5 in Claude Code.
🤖 Generated with Claude Code
Verdict: Needs Human Approval
Macroscope's review found this PR requires human approval — This PR adds a new background-wait tool and changes when monitors keep threads in Working or trigger restart recovery. Because it changes product defaults and affects thread lifecycle behavior across server and client layers, the change warrants human review.
You can add or adjust custom eligibility rules. Learn more.
âś… Thread transfer remains within every enforced ceiling.
ℹ️ The exact PR base did not have a successful artifact. Baseline uses the latest successful
mainmeasurement shown below.
| Provider | Metric | Main baseline | This PR | Impact | PR ceiling | |
|---|---|---|---|---|---|---|
| Codex | Total thread wire | 5.0 KiB | 5.0 KiB | 0 B (0.0%) | 6.8 KiB | âś… |
| Codex | Thread snapshot wire | 3.8 KiB | 3.8 KiB | 0 B (0.0%) | 4.9 KiB | âś… |
| Codex | Live turn WebSocket wire | 1.2 KiB | 1.2 KiB | 0 B (0.0%) | 2.0 KiB | âś… |
| Codex | Live turn WebSocket decoded | 20.9 KiB | 20.9 KiB | 0 B (0.0%) | 29.3 KiB | âś… |
| Codex | Live turn messages | 2 | 2 | 0 (0.0%) | 8 | âś… |
| Claude | Total thread wire | 5.0 KiB | 5.0 KiB | 0 B (0.0%) | 6.8 KiB | âś… |
| Claude | Thread snapshot wire | 3.8 KiB | 3.8 KiB | 0 B (0.0%) | 4.9 KiB | âś… |
| Claude | Live turn WebSocket wire | 1.2 KiB | 1.2 KiB | 0 B (0.0%) | 2.0 KiB | âś… |
| Claude | Live turn WebSocket decoded | 21.2 KiB | 21.2 KiB | 0 B (0.0%) | 29.3 KiB | âś… |
| Claude | Live turn messages | 2 | 2 | 0 (0.0%) | 8 | âś… |
Baseline: 8bcef34 · PR result: 1d989a7 · Source CI: success
10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.
Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.
No actionable comments were generated in the recent review.
1232a95b-345a-4df1-ac52-8d19e1f6cf39Reviewing files that changed from the base of the PR and between d2bc1f9e1d8804771d3713cd1937ad7166f17d3f and 1d989a7862b342ee294f039be6b8c25dd6816d85.
apps/server/src/mcp/toolkits/orchestrator/tools.tsLimit details: You’ve used all 10 included reviews currently available.
The change adds an MCP tool to mark background tasks as awaited. Provider task rosters carry the awaited marker, and completion, restart-continuation, and thread-status behavior distinguish awaited work from other running commands and monitors.
Changes: Background wait behavior
| Layer / File(s) | Summary |
|---|---|
Track awaited tasks on provider threads packages/contracts/src/orchestrationV2.ts, packages/provider-core/src/server/ProviderAdapter.ts, apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts, apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts | The contracts add an optional awaited: true marker. The provider runtime adds an operation to mark or unmark task IDs. The Claude adapter tracks marks by thread, includes them in rosters, and removes them when tasks leave the roster. |
Expose background waits through orchestration apps/server/src/orchestration-v2/ThreadManagementService.ts, apps/server/src/orchestration-v2/ThreadManagementService.test.ts, apps/server/src/mcp/toolkits/orchestrator/*, packages/shared/src/t3McpToolPresentation.ts, packages/client-runtime/src/t3ToolSummary.ts, packages/client-runtime/src/work-log/presentation.ts | The thread-management service calls the provider runtime and returns matched and unmatched IDs. The t3_background_wait MCP tool accepts task IDs and an optional waiting flag. Tool presentation and summaries include the new action. |
Apply awaited state to completion and thread status packages/shared/src/orchestrationV2PendingBackgroundWork.ts, apps/server/src/orchestration-v2/RestartBackgroundNote.ts, apps/server/src/orchestration-v2/runtimeLayer.test.ts, apps/server/src/orchestration-v2/RestartBackgroundNote.test.ts, apps/server/src/orchestration-v2/RestartContinuation.test.ts, apps/server/src/orchestration-v2/DelegatedCompletionDelivery.test.ts, apps/server/src/orchestration-v2/ProjectionStore.test.ts, packages/shared/src/*test.ts, packages/client-runtime/src/state/*, apps/server/src/relay/AgentAwarenessRelay.test.ts, apps/web/src/components/Sidebar.logic.test.ts, apps/mobile/src/features/threads/threadListV2.test.ts, docs/internals/server-updates.md, docs/user/thread-sidebar.md, docs/user/updating.md | Commands and monitors hold completion when marked awaited; unmarked commands and monitors do not. Restart handling carries the awaited marker into cancelled-work checks. Tests and documentation reflect completion and thread-status behavior. |
Priority: External image Normal
Estimated code review effort: 3 (Moderate) | ~25 minutes
Change: Bug fix · Severity of issue fixed: Medium
| 1 | sequenceDiagram |
| 2 | participant OrchestratorToolkit |
| 3 | participant ThreadManagementService |
| 4 | participant ProviderAdapterV2SessionRuntime |
| 5 | participant ClaudeAdapterV2 |
| 6 | OrchestratorToolkit->>ThreadManagementService: Submit task IDs and waiting flag |
| 7 | ThreadManagementService->>ProviderAdapterV2SessionRuntime: Mark tasks on provider thread |
| 8 | ProviderAdapterV2SessionRuntime->>ClaudeAdapterV2: Match IDs and update awaited marks |
| 9 | ClaudeAdapterV2-->>ProviderAdapterV2SessionRuntime: Return matched IDs and updated roster |
| 10 | ProviderAdapterV2SessionRuntime-->>ThreadManagementService: Return matched IDs |
| 11 | ThreadManagementService-->>OrchestratorToolkit: Return matched and unmatched IDs |
Possibly related issues
Possibly related PRs
Suggested labels: bugfix, takeover
Suggested reviewers: juliusmarminge, macroscopeapp
1d989No actionable merge-blocking risk is established for this change.
| Check name | Status | Explanation |
|---|---|---|
| Title check | Passed | The title "fix(threads): Working holds only background work the agent waits on" matches the main change. The changeset adds an agent-driven t3_background_wait mark and changes `backgroundWorkHoldsCo… |
| Description check | Passed | The description follows the template's main sections: Problem, Change, Scope and approval, and Verification. It explains the problem and the fix, and it lists the live runs and test suites that were r… |
| Linked Issues check | Passed | Check skipped because no linked issues were found for this pull request. |
| Out of Scope Changes check | Passed | Check skipped because no linked issues were found for this pull request. |
Explanation
The title "fix(threads): Working holds only background work the agent waits on" matches the main change. The changeset adds an agent-driven t3_background_wait mark and changes backgroundWorkHoldsCompletion so unmarked commands and monitors no longer hold a thread in Working. The title is concise, uses a conventional commit prefix, and names the primary behavior change.
Explanation
The description follows the template's main sections: Problem, Change, Scope and approval, and Verification. It explains the problem and the fix, and it lists the live runs and test suites that were run. It links the replaced PR #22055 and the screenshots. The Scope and approval section does not link a triaged issue or maintainer approval, and it does not explain why the change qualifies without one. The description also has no explicit Problem heading for the bug reproduction steps beyond the live runs. The description is mostly complete, so the check passes, but the missing approval link should be added.
Note
This review was completed with usage-based billing: files reviewed beyond your plan's included limits are billed at $0.25/file. View usage-based billing.
Comment @coderabbitai help to get the list of available commands.
Added 5 commits