fix(server): queue background notifications during active tools

[Yash-Singh1]

Automatic child-completion notices and scheduled prompts could interrupt Claude's pending tools. Claude then returned cancellation text that the parent model interpreted as a user refusal.

Keep Claude child-completion notices in T3's durable queue by recording that its native steering cancels pending tools. Bound scheduled prompts also queue behind active work. Explicit user steering retains its immediate behavior. Preserve native per-tool non-execution metadata and project cancelled calls as cancelled, distinct from permission denials.

For Claude, completionWake: always now delivers after the active run finishes. Existing delivery identities, deduplication, and recovery remain in use.

Validation after merging current main:

• 223 focused tests passed across nine files, including the Bash command plus four pending status reads, child-completion and scheduled delivery, explicit steering, permission denials, completion races, recovery, and upstream background-work Stop behavior.
• Server and contracts typechecks passed.
• Targeted lint passed with two existing unused-variable warnings.

The regression replays the captured native frame shapes and Claude's queue-abort behavior through the real T3 services and adapter. It does not run a live Claude session. The live T3 database and installed application were untouched.

Closes #15351

Model: GPT 6.1 Sol. Harness: Codex.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes scheduled prompts from automatic dispatch to queued dispatch and alters Claude's active-tool steering behavior, affecting production orchestration semantics. The scheduled-task default change requires human review.

No code changes detected at f3f6efd. Prior analysis still applies.

^{You can add or adjust custom eligibility rules. Learn more.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

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	+41 B (+0.8%)	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	+41 B (+3.4%)	2.0 KiB	✅
Claude	Live turn WebSocket decoded	21.2 KiB	21.2 KiB	+41 B (+0.2%)	29.3 KiB	✅
Claude	Live turn messages	1	2	+1 (+100.0%)	8	✅

Baseline: a1d9d72 · PR result: f3f6efd · Source CI: success

Scenario and decoded snapshot size

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.

• Codex decoded thread snapshot: 108.5 KiB
• Claude decoded thread snapshot: 108.8 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: pingdotgg/t3code/.coderabbit.yaml
• Review profile: CHILL
• Plan: Team
• Run ID: efa4da68-5df0-4efa-8b7d-13646594a679

📥 Commits

Reviewing files that changed from the base of the PR and between 8dd73ca and f3f6efd.

📒 Files selected for processing (3)

• apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts
• apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts
• apps/server/src/orchestration-v2/Orchestrator.ts

Included review availability: This review used your included allowance. 8 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 10 reviews per hour.

---

📝 Walkthrough

Walkthrough

The Claude adapter now records native tool non-execution metadata and marks cancelled tool results. Orchestration uses provider capability information when selecting delegated-completion delivery behavior. Scheduled prompts to existing threads use queue mode. Tests cover adapter results, steering behavior, and delivery scenarios.

Changes

Claude orchestration

Layer / File(s)	Summary
Claude tool metadata packages/contracts/src/orchestrationV2.ts, apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts, apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts, packages/contracts/src/orchestrationV2.test.ts	Turn items support optional toolNonExecutionKind, and turn capabilities support activeSteeringInterruptsTools. The Claude adapter reads SDK metadata and marks tool results cancelled when the kind is cancelled. Tests cover metadata values, contract round-tripping, and permission refusals.
Steering and queued delivery apps/server/src/orchestration-v2/Orchestrator.ts, apps/server/src/scheduledTasks/ScheduledTaskService.ts, apps/server/src/orchestration-v2/SteeringCompletion.integration.test.ts	Delegated-completion dispatch excludes providers whose active steering interrupts tools. Scheduled prompts to existing threads use queue mode. Steering completion tests include interrupting native steering.
Delivery and interruption integration coverage apps/server/src/orchestration-v2/ClaudeAutomaticDelivery.integration.test.ts	The integration test replays Claude messages for child completion, scheduled delivery, and user steering. It checks tool-result status and metadata, delivery outcomes, deduplication, and recovery.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant Orchestrator
  participant ScheduledTaskService
  participant ClaudeAdapterV2
  participant ClaudeSDK
  alt User steering
    User->>Orchestrator: Dispatch steer-active message
    Orchestrator->>ClaudeSDK: Offer priority-now message
    ClaudeSDK->>ClaudeAdapterV2: Return cancelled tool results and metadata
    ClaudeAdapterV2->>Orchestrator: Project cancelled items
  else Automatic delivery
    ScheduledTaskService->>Orchestrator: Dispatch existing-thread prompt in queue mode
    ClaudeSDK->>ClaudeAdapterV2: Return completed tool results
    ClaudeAdapterV2->>Orchestrator: Project completed tool items
    Orchestrator->>Orchestrator: Process queued delivery
  end

Loading

Suggested reviewers: juliusmarminge

Merge Risk: ⚪ Minimal · up to f3f6e

Claude background notifications are routed away from active steering during tool work. No merge-blocking issue is established by the available evidence.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 5 functions across 8 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Issue #15351 requires child-completion notices to reach the agent without cancelling pending tool calls. Claude now reports that active steering interrupts tools, and the orchestrator therefore avoids…
Out of Scope Changes check	✅ Passed	The scheduled-prompt queue behavior, capability contract, cancellation metadata, and tests support the notification-interruption fix in #15351. The reviewed changes show no unrelated modifications.
Title check	✅ Passed	The title clearly and concisely describes the main change: queueing background notifications while tools are active.
Description check	✅ Passed	The description explains the problem, change, scope, and focused verification results. It links issue #15351, but it does not state maintainer approval or explain why the change qualifies for an excep…

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

_{Comment @coderabbitai help to get the list of available commands.}

[Yash-Singh1]

Note

Generated by GPT 6.1 Sol

I am leaving CodeRabbit's 80% docstring-coverage suggestion unimplemented. The project's AGENTS.md asks comments to explain usage and constraints that are difficult to discover from the code. The new code already explains the undeclared SDK metadata and the native cancellation replay. Adding generic docstrings to meet a percentage would expand this fix without clarifying its behavior.

After merging current main, all 223 focused tests passed, along with the server and contracts typechecks. The PR description now records those results and the replay's limitations.