Skip to content

Commit 0ced527

Browse files
Alb11747codex
andcommitted
fix(server): agent messages no longer cancel Claude tools
Deliver Claude agent updates through root PostToolBatch and Stop hook context without interrupting running tools. Defer to the durable next-turn queue after five seconds without a boundary, or when the update contains attachments. Let human steering and immediate controls pass a waiting boundary delivery. Revoke pending updates on Stop and task disposal, and refresh completion pointers when only part of a task cohort remains unacknowledged. Keep native human steering and other providers' delivery behavior unchanged. Exercise the real send service, hook adapter, outbox ordering and ownership races with deterministic regression coverage. Upstream-PR: #21158 Co-Authored-By: GPT-6.1 Sol at high effort, implementation and SDK research <[email protected]> Co-Authored-By: GPT-6.1 Sol at xhigh effort, independent review <[email protected]>
1 parent 92a6b43 commit 0ced527

15 files changed

Lines changed: 1379 additions & 117 deletions

‎apps/server/src/mcp/OrchestratorMcpToolkit.integration.test.ts‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -561,7 +561,15 @@ describe("orchestrator MCP toolkit", () => {
561561
makeDeterministicAdapter({
562562
instanceId: claudeInstanceId,
563563
driver: ProviderDriverKind.make("claudeAgent"),
564-
capabilities: ClaudeProviderCapabilitiesV2,
564+
capabilities: {
565+
...ClaudeProviderCapabilitiesV2,
566+
turns: {
567+
...ClaudeProviderCapabilitiesV2.turns,
568+
// This deterministic adapter steers without interrupting tools.
569+
// Real Claude uses boundary hooks, covered by SteeringCompletion.
570+
activeSteeringInterruptsTools: false,
571+
},
572+
},
565573
capturedTurns,
566574
shouldComplete: (turn) => turn.message.text !== cancellationPrompt,
567575
terminalGate: (turn) =>

‎apps/server/src/mcp/toolkits/orchestrator/tools.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -234,7 +234,7 @@ export const ThreadUpdateTool = Tool.make("t3_thread_update", {
234234

235235
const ThreadSendTool = Tool.make("t3_thread_send", {
236236
description:
237-
"Send a message to any T3 thread in this environment. The target cannot have broader permission modes than the caller. Use delegate_task with the full review context and a new clientRequestId for independent review rounds. For a follow-up that needs the same child's conversation, send to its childThreadId. After the original task completes, a requested follow-up creates a fresh task in that child thread and returns taskId when it starts a turn or restarts a turn without its own task; its completion notifies the parent, and the original result stays unchanged. A steer that joins a running turn returns that turn's task, if it has one. mode='auto' starts an idle thread, steers a fully active turn, or queues behind a turn that is not yet steerable. Use queue for a separate follow-up turn, steer for an in-flight update, or restart to interrupt-and-restart the active turn. clientRequestId makes retries idempotent.",
237+
"Send a message to any T3 thread in this environment. The target cannot have broader permission modes than the caller. Use delegate_task with the full review context and a new clientRequestId for independent review rounds. For a follow-up that needs the same child's conversation, send to its childThreadId. After the original task completes, a requested follow-up creates a fresh task in that child thread and returns taskId when it starts a turn or restarts a turn without its own task; its completion notifies the parent, and the original result stays unchanged. A steer that joins a running turn returns that turn's task, if it has one. mode='auto' starts an idle thread, safely steers a fully active turn, or queues behind a turn that is not yet steerable. Claude agent updates wait for a safe tool-batch or answer boundary for up to five seconds, then queue a separate turn if no boundary arrives. Other tool-interrupting sessions queue immediately. delivery reports dispatch acceptance, not model processing. Use queue for a separate follow-up turn, steer for an in-flight update, or restart to explicitly interrupt-and-restart the active turn. clientRequestId makes retries idempotent.",
238238
parameters: OrchestratorMcpThreadSendInput,
239239
success: OrchestratorMcpThreadSendResult,
240240
failure: OrchestratorMcpFailure,

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

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2669,6 +2669,136 @@ describe("ClaudeAdapterV2 background wake turns", () => {
26692669
});
26702670
const makeWakeHarness = makeWakeHarnessWithOptions();
26712671

2672+
it.effect.each([
2673+
"PostToolBatch",
2674+
"Stop",
2675+
"timeout",
2676+
"cancelled",
2677+
"completed",
2678+
"withdrawn",
2679+
"refreshed",
2680+
"aborted",
2681+
] as const)("delivers agent messages at a safe boundary or defers them (%s)", (scenario) =>
2682+
Effect.scoped(
2683+
Effect.gen(function* () {
2684+
const harness = yield* makeWakeHarnessWithOptions({ close: Queue.shutdown });
2685+
const allocator = yield* IdAllocator.IdAllocatorV2;
2686+
const hookAbort = new AbortController();
2687+
const attemptId = RunAttemptId.make("attempt-agent-boundary");
2688+
const input = makeClaudeTestTurnInput({
2689+
threadId: harness.threadId,
2690+
providerThread: harness.providerThread,
2691+
now: yield* DateTime.now,
2692+
attemptId,
2693+
text: "Work through the task.",
2694+
attachments: [],
2695+
});
2696+
yield* harness.runtime.startTurn(input);
2697+
const turn = {
2698+
threadId: harness.threadId,
2699+
runId: input.runId,
2700+
providerThread: harness.providerThread,
2701+
providerTurnId: allocator.derive.providerTurn({
2702+
driver: ClaudeAdapterV2.CLAUDE_PROVIDER,
2703+
nativeTurnId: `turn:${attemptId}`,
2704+
}),
2705+
};
2706+
const steering = yield* harness.runtime
2707+
.steerTurn({
2708+
...turn,
2709+
...(scenario === "withdrawn" || scenario === "refreshed" || scenario === "aborted"
2710+
? {
2711+
resolveMessageText: Effect.sync(() => {
2712+
if (scenario === "aborted") hookAbort.abort();
2713+
return scenario === "withdrawn" ? undefined : "Remaining task completed.";
2714+
}),
2715+
}
2716+
: {}),
2717+
message: {
2718+
createdBy: "agent",
2719+
creationSource: "mcp",
2720+
messageId: MessageId.make("agent-boundary-update"),
2721+
text: "The review found a missing check.",
2722+
attachments: [],
2723+
},
2724+
})
2725+
.pipe(Effect.forkScoped);
2726+
// Flush runnable fibers; the steer is now waiting on its boundary.
2727+
yield* TestClock.adjust("0 millis");
2728+
const event = scenario === "Stop" ? "Stop" : "PostToolBatch";
2729+
const hook = harness.getOpenedOptions()?.hooks?.[event]?.[0]?.hooks[0];
2730+
assert.isDefined(hook);
2731+
const boundary =
2732+
event === "Stop"
2733+
? { hook_event_name: "Stop" as const, stop_hook_active: false }
2734+
: { hook_event_name: "PostToolBatch" as const, tool_calls: [] };
2735+
const hookInput = {
2736+
...boundary,
2737+
session_id: WAKE_NATIVE_SESSION,
2738+
transcript_path: "transcript.jsonl",
2739+
cwd: "/repo",
2740+
};
2741+
const callHook = (child = false, signal = hookAbort.signal) =>
2742+
Effect.promise(() =>
2743+
hook!({ ...hookInput, ...(child ? { agent_id: "child" } : {}) }, undefined, {
2744+
signal,
2745+
}),
2746+
);
2747+
assert.deepEqual(yield* callHook(true), {});
2748+
if (scenario === "timeout") {
2749+
yield* TestClock.adjust("5 seconds");
2750+
} else if (scenario === "cancelled") {
2751+
yield* harness.runtime.interruptTurn(turn);
2752+
} else if (scenario === "completed") {
2753+
yield* harness.offerAndWait(
2754+
makeResultFrame({ uuid: "boundary-completed", result: "Done" }),
2755+
);
2756+
} else {
2757+
const output = yield* callHook();
2758+
assert.deepEqual(
2759+
output,
2760+
scenario === "withdrawn" || scenario === "aborted"
2761+
? {}
2762+
: {
2763+
hookSpecificOutput: {
2764+
hookEventName: event,
2765+
additionalContext:
2766+
scenario === "refreshed"
2767+
? "New message from another agent:\nRemaining task completed."
2768+
: "New message from another agent:\nThe review found a missing check.",
2769+
},
2770+
},
2771+
);
2772+
if (scenario === "aborted") {
2773+
assert.deepEqual(yield* callHook(false, new AbortController().signal), {
2774+
hookSpecificOutput: {
2775+
hookEventName: event,
2776+
additionalContext: "New message from another agent:\nRemaining task completed.",
2777+
},
2778+
});
2779+
}
2780+
}
2781+
if (
2782+
scenario === "timeout" ||
2783+
scenario === "completed" ||
2784+
scenario === "cancelled" ||
2785+
scenario === "withdrawn"
2786+
) {
2787+
const error = yield* Fiber.join(steering).pipe(Effect.flip);
2788+
assert.equal(error._tag, "ProviderAdapterSteerRunDeferredError");
2789+
} else {
2790+
yield* Fiber.join(steering);
2791+
}
2792+
assert.deepEqual(yield* callHook(), {});
2793+
assert.equal(harness.offeredMessages.length, 1);
2794+
}).pipe(
2795+
Effect.provide(
2796+
Layer.mergeAll(IdAllocator.layer, McpProviderSessions.layer, NodeServices.layer),
2797+
),
2798+
),
2799+
),
2800+
);
2801+
26722802
it.effect.each([
26732803
{ isError: false, title: "Check weather" },
26742804
{ isError: true, title: "Check weather" },

‎apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts‎

Lines changed: 137 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ import {
2626
type EffortLevel,
2727
type ForkSessionOptions,
2828
type ForkSessionResult,
29+
type HookCallback,
2930
getSubagentMessages,
3031
query,
3132
type Options as ClaudeQueryOptions,
@@ -319,6 +320,7 @@ export const ClaudeProviderCapabilitiesV2 = {
319320
supportsInterrupt: true,
320321
supportsActiveSteering: true,
321322
activeSteeringInterruptsTools: true,
323+
supportsNonInterruptingAgentSteering: true,
322324
supportsSteeringByInterruptRestart: false,
323325
supportsQueuedMessages: true,
324326
terminalStatusQuality: "strong",
@@ -3016,6 +3018,15 @@ function formatClaudeUsageLimitWait(waitMs: number): string {
30163018
return minutes === 0 ? `${hours}h` : `${hours}h ${minutes}m`;
30173019
}
30183020

3021+
type ClaudeAgentSteerOutcome = "delivered" | "deferred" | "cancelled";
3022+
3023+
interface PendingClaudeAgentSteer {
3024+
readonly text: string;
3025+
readonly completion: Deferred.Deferred<ClaudeAgentSteerOutcome>;
3026+
readonly resolveMessageText?: ProviderAdapter.ProviderAdapterV2SteerInput["resolveMessageText"];
3027+
outcome?: ClaudeAgentSteerOutcome;
3028+
}
3029+
30193030
interface ActiveClaudeTurnContext {
30203031
readonly input: ProviderAdapter.ProviderAdapterV2TurnInput;
30213032
readonly nativeThreadId: string;
@@ -3073,12 +3084,26 @@ interface ActiveClaudeTurnContext {
30733084
readonly subagentsByToolUseId: Map<string, ActiveClaudeSubagent>;
30743085
readonly subagentNodesByTaskId: Map<string, OrchestrationV2ExecutionNode["id"]>;
30753086
readonly promptUuid: string | null;
3087+
readonly pendingAgentSteers: Map<string, PendingClaudeAgentSteer>;
30763088
promptEcho: "pending" | "confirmed";
30773089
promptStarted: boolean;
30783090
gatedFramesBeforeEcho: number;
30793091
readonly heldRootFrames: Array<SDKMessage>;
30803092
}
30813093

3094+
// Claim and acknowledge synchronously so a boundary racing the timeout cannot
3095+
// both inject a message and return it to the durable queue.
3096+
function settleClaudeAgentSteers(
3097+
context: ActiveClaudeTurnContext,
3098+
outcome: ClaudeAgentSteerOutcome,
3099+
): void {
3100+
for (const pending of context.pendingAgentSteers.values()) {
3101+
pending.outcome = outcome;
3102+
Deferred.doneUnsafe(pending.completion, Effect.succeed(outcome));
3103+
}
3104+
context.pendingAgentSteers.clear();
3105+
}
3106+
30823107
interface ActiveClaudeProviderRetry {
30833108
readonly retry: OrchestrationV2ProviderRetry;
30843109
readonly failure: OrchestrationV2ProviderFailure;
@@ -6066,6 +6091,12 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* (
60666091
readonly threadDisposition?: "reusable" | "broken";
60676092
readonly result?: SDKResultMessage;
60686093
}) {
6094+
settleClaudeAgentSteers(
6095+
input.context,
6096+
input.status === "interrupted" || input.status === "cancelled"
6097+
? "cancelled"
6098+
: "deferred",
6099+
);
60696100
yield* reasoningDeltas.flushTurn(input.context.nativeTurnId);
60706101
if (input.context.compaction?.status === "running") {
60716102
yield* emitProviderEvent({
@@ -8644,11 +8675,68 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* (
86448675
onUserDialog,
86458676
supportedDialogKinds: ["resume_return"],
86468677
});
8678+
let boundaryQuery: ClaudeAgentSdkQuerySession | undefined;
8679+
const agentMessageBoundary: HookCallback = (hookInput, _toolUseId, options) =>
8680+
runPromise(
8681+
Effect.gen(function* () {
8682+
const context = yield* Ref.get(activeTurn);
8683+
const live = yield* Ref.get(queryContext);
8684+
if (
8685+
options.signal.aborted ||
8686+
hookInput.agent_id !== undefined ||
8687+
context === null ||
8688+
live?.query !== boundaryQuery ||
8689+
live?.stopping ||
8690+
context.nativeThreadId !== hookInput.session_id ||
8691+
(yield* Ref.get(interruptedTurns)).has(context.providerTurnId) ||
8692+
(hookInput.hook_event_name !== "PostToolBatch" &&
8693+
hookInput.hook_event_name !== "Stop")
8694+
) {
8695+
return {};
8696+
}
8697+
// Resolve before claiming so an aborted hook consumes no partial batch.
8698+
const pendingSteers = yield* Effect.forEach(
8699+
Array.from(context.pendingAgentSteers),
8700+
([id, pending]) =>
8701+
(pending.resolveMessageText ?? Effect.succeed(pending.text)).pipe(
8702+
Effect.map((text) => ({ id, pending, text })),
8703+
),
8704+
);
8705+
const liveTurn =
8706+
(yield* Ref.get(activeTurn)) === context &&
8707+
(yield* Ref.get(queryContext)) === live &&
8708+
!(yield* Ref.get(interruptedTurns)).has(context.providerTurnId);
8709+
if (options.signal.aborted) return {};
8710+
const messages: string[] = [];
8711+
for (const { id, pending, text } of pendingSteers) {
8712+
// The deadline or cancellation can win while storage is read.
8713+
if (context.pendingAgentSteers.get(id) !== pending) continue;
8714+
pending.outcome = text !== undefined && liveTurn ? "delivered" : "cancelled";
8715+
context.pendingAgentSteers.delete(id);
8716+
Deferred.doneUnsafe(pending.completion, Effect.succeed(pending.outcome));
8717+
if (pending.outcome === "delivered" && text !== undefined) messages.push(text);
8718+
}
8719+
return messages.length === 0
8720+
? {}
8721+
: {
8722+
hookSpecificOutput: {
8723+
hookEventName: hookInput.hook_event_name,
8724+
additionalContext: `New message from another agent:\n${messages.join("\n\n")}`,
8725+
},
8726+
};
8727+
}),
8728+
);
86478729
const querySession = yield* queryRunner
86488730
.open({
86498731
threadId: turnInput.threadId,
86508732
providerSessionId: input.providerSessionId,
8651-
options: queryOptions,
8733+
options: {
8734+
...queryOptions,
8735+
hooks: {
8736+
PostToolBatch: [{ hooks: [agentMessageBoundary] }],
8737+
Stop: [{ hooks: [agentMessageBoundary] }],
8738+
},
8739+
},
86528740
})
86538741
.pipe(
86548742
Effect.onError(() =>
@@ -8662,6 +8750,7 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* (
86628750
: Effect.void,
86638751
),
86648752
);
8753+
boundaryQuery = querySession;
86658754
// Marked only after a successful open: a failed create must not
86668755
// leave the runtime believing the native session exists, or the
86678756
// retry would resume a session that was never created.
@@ -8834,6 +8923,7 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* (
88348923
latestAssistantRateLimited: false,
88358924
compactionFailure: null,
88368925
steeredSegmentUsage: [],
8926+
pendingAgentSteers: new Map(),
88378927
subagentsByTaskId: new Map(),
88388928
subagentsByToolUseId: new Map(),
88398929
subagentNodesByTaskId: new Map(),
@@ -9025,6 +9115,7 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* (
90259115
next.add(turnInput.providerTurnId);
90269116
return next;
90279117
});
9118+
settleClaudeAgentSteers(currentTurn, "cancelled");
90289119
yield* existing.query.interrupt;
90299120
yield* existing.query.close.pipe(Effect.ignore);
90309121
const closed = yield* Deferred.await(existing.closed).pipe(
@@ -9150,6 +9241,42 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* (
91509241
detail: `Claude provider turn ${turnInput.providerTurnId} is not the active turn.`,
91519242
});
91529243
}
9244+
if (turnInput.message.createdBy === "agent") {
9245+
// `priority: next` also folds after tools, but can start an unowned
9246+
// native turn if the answer ends first. Hooks keep delivery owned
9247+
// by this turn; an absent/slow boundary falls back to T3's queue.
9248+
if (turnInput.message.attachments.length > 0) {
9249+
return yield* new ProviderAdapter.ProviderAdapterSteerRunDeferredError({
9250+
driver: CLAUDE_PROVIDER,
9251+
providerThreadId: turnInput.providerThread.id,
9252+
providerTurnId: turnInput.providerTurnId,
9253+
});
9254+
}
9255+
const pending: PendingClaudeAgentSteer = {
9256+
text: turnInput.message.text,
9257+
completion: yield* Deferred.make<ClaudeAgentSteerOutcome>(),
9258+
...(turnInput.resolveMessageText === undefined
9259+
? {}
9260+
: { resolveMessageText: turnInput.resolveMessageText }),
9261+
};
9262+
currentTurn.pendingAgentSteers.set(turnInput.message.messageId, pending);
9263+
yield* Deferred.await(pending.completion).pipe(
9264+
Effect.timeoutOption("5 seconds"),
9265+
Effect.ensuring(
9266+
Effect.sync(() => {
9267+
currentTurn.pendingAgentSteers.delete(turnInput.message.messageId);
9268+
}),
9269+
),
9270+
);
9271+
if (pending.outcome === "delivered") return;
9272+
// A restart can interrupt this wait too. Let the caller revoke
9273+
// stopped/disposed input or retain still-owned input in its queue.
9274+
return yield* new ProviderAdapter.ProviderAdapterSteerRunDeferredError({
9275+
driver: CLAUDE_PROVIDER,
9276+
providerThreadId: turnInput.providerThread.id,
9277+
providerTurnId: turnInput.providerTurnId,
9278+
});
9279+
}
91539280
const userMessage = yield* makeClaudeUserMessageWithAttachments({
91549281
text: applyClaudePromptEffortPrefix(
91559282
turnInput.message.text,
@@ -9183,14 +9310,15 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* (
91839310
},
91849311
(effect, turnInput) =>
91859312
effect.pipe(
9186-
Effect.mapError(
9187-
(cause) =>
9188-
new ProviderAdapter.ProviderAdapterSteerRunError({
9189-
driver: CLAUDE_PROVIDER,
9190-
providerThreadId: turnInput.providerThread.id,
9191-
providerTurnId: turnInput.providerTurnId,
9192-
cause,
9193-
}),
9313+
Effect.mapError((cause) =>
9314+
cause._tag === "ProviderAdapterSteerRunDeferredError"
9315+
? cause
9316+
: new ProviderAdapter.ProviderAdapterSteerRunError({
9317+
driver: CLAUDE_PROVIDER,
9318+
providerThreadId: turnInput.providerThread.id,
9319+
providerTurnId: turnInput.providerTurnId,
9320+
cause,
9321+
}),
91949322
),
91959323
),
91969324
);

0 commit comments

Comments
 (0)