Skip to content

Commit de5e500

Browse files
Jreevoclaude
andcommitted
fix(server): a Claude subagent waiting on its own background work no longer shows as finished
Claude Code reports a background subagent `completed` when its turn ends, even while background work it started still runs, and resumes it under the same task id once that work finishes. Keep such a subagent running, using the parent_task_id ownership Claude reports on roster entries and task_started frames. Settle it at the next turn if the work ends without a resume. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
1 parent f4f148e commit de5e500

2 files changed

Lines changed: 551 additions & 4 deletions

File tree

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

Lines changed: 337 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7015,6 +7015,343 @@ describe("ClaudeAdapterV2 background wake turns", () => {
70157015
),
70167016
);
70177017

7018+
// Shaped like a recorded session: a background subagent starts a background
7019+
// shell command and ends its turn to wait for it. Claude reports the
7020+
// subagent `completed` while the shell still runs, then resumes it under the
7021+
// same task id and tool_use_id when the shell finishes.
7022+
const OWN_WORK_SUBAGENT_TASK_ID = "task-own-background-work";
7023+
const OWN_WORK_SUBAGENT_TOOL_USE_ID = "toolu-own-background-work";
7024+
const OWN_WORK_SHELL_TASK_ID = "shell-own-background-work";
7025+
const OWN_WORK_INTERIM_SUMMARY = "I'll wait for the completion notification.";
7026+
const ownWorkSubagentStarted = (uuid: string, prompt: string) =>
7027+
claudeSdkFrame({
7028+
type: "system",
7029+
subtype: "task_started",
7030+
task_id: OWN_WORK_SUBAGENT_TASK_ID,
7031+
tool_use_id: OWN_WORK_SUBAGENT_TOOL_USE_ID,
7032+
description: "Run the UI journeys",
7033+
subagent_type: "general-purpose",
7034+
is_backgrounded: true,
7035+
task_type: "local_agent",
7036+
prompt,
7037+
uuid,
7038+
session_id: WAKE_NATIVE_SESSION,
7039+
});
7040+
const ownWorkSubagentNotification = (uuid: string, summary: string) =>
7041+
claudeSdkFrame({
7042+
type: "system",
7043+
subtype: "task_notification",
7044+
task_id: OWN_WORK_SUBAGENT_TASK_ID,
7045+
tool_use_id: OWN_WORK_SUBAGENT_TOOL_USE_ID,
7046+
status: "completed",
7047+
output_file: "/tmp/task-own-background-work.output",
7048+
summary,
7049+
uuid,
7050+
session_id: WAKE_NATIVE_SESSION,
7051+
});
7052+
const ownWorkShellNotification = claudeSdkFrame({
7053+
type: "system",
7054+
subtype: "task_notification",
7055+
task_id: OWN_WORK_SHELL_TASK_ID,
7056+
tool_use_id: "toolu-own-background-work-shell",
7057+
status: "completed",
7058+
output_file: "/tmp/shell-own-background-work.output",
7059+
summary: 'Background command "Run the UI journeys" completed (exit code 0)',
7060+
uuid: "00000000-0000-4000-8000-000000001708",
7061+
session_id: WAKE_NATIVE_SESSION,
7062+
});
7063+
const ownWorkSubagentEvents = (events: ReadonlyArray<ProviderAdapterV2Event>) =>
7064+
events.filter(
7065+
(event): event is Extract<ProviderAdapterV2Event, { type: "subagent.updated" }> =>
7066+
event.type === "subagent.updated",
7067+
);
7068+
7069+
// Runs the subagent up to its interim `completed`, drained by a continuation.
7070+
const runOwnWorkSubagentToInterimCompletion = Effect.fnUntraced(function* (
7071+
harness: Effect.Success<typeof makeWakeHarness>,
7072+
options?: { readonly launchTurnFails?: boolean },
7073+
) {
7074+
const now = yield* DateTime.now;
7075+
yield* harness.runtime.startTurn(
7076+
makeClaudeTestTurnInput({
7077+
threadId: harness.threadId,
7078+
providerThread: harness.providerThread,
7079+
now,
7080+
attemptId: RunAttemptId.make("attempt-claude-own-work-1"),
7081+
text: "Start a background subagent and stop.",
7082+
attachments: [],
7083+
}),
7084+
);
7085+
yield* Queue.offer(
7086+
harness.sdkMessages,
7087+
ownWorkSubagentStarted(
7088+
"00000000-0000-4000-8000-000000001701",
7089+
"Run the UI journeys and report the result.",
7090+
),
7091+
);
7092+
yield* awaitUntil(
7093+
() => ownWorkSubagentEvents(harness.events).length >= 1,
7094+
"subagent node created",
7095+
);
7096+
yield* Queue.offer(
7097+
harness.sdkMessages,
7098+
makeResultFrame({
7099+
uuid: "00000000-0000-4000-8000-000000001702",
7100+
result: "Started the subagent in the background.",
7101+
...(options?.launchTurnFails === true
7102+
? { subtype: "error_during_execution", isError: true, errors: ["Turn failed."] }
7103+
: {}),
7104+
}),
7105+
);
7106+
yield* awaitUntil(() => harness.terminalEvents().length === 1, "first turn terminal");
7107+
7108+
// While the root is idle, the subagent starts its own background shell.
7109+
yield* harness.offerAndWait(
7110+
claudeSdkFrame({
7111+
type: "system",
7112+
subtype: "task_started",
7113+
task_id: OWN_WORK_SHELL_TASK_ID,
7114+
tool_use_id: "toolu-own-background-work-shell",
7115+
description: "Run the UI journeys",
7116+
is_backgrounded: true,
7117+
owned_by_subagent: true,
7118+
parent_task_id: OWN_WORK_SUBAGENT_TASK_ID,
7119+
task_type: "local_bash",
7120+
uuid: "00000000-0000-4000-8000-000000001703",
7121+
session_id: WAKE_NATIVE_SESSION,
7122+
}),
7123+
);
7124+
yield* harness.offerAndWait(
7125+
claudeSdkFrame({
7126+
type: "system",
7127+
subtype: "background_tasks_changed",
7128+
tasks: [
7129+
{ task_id: OWN_WORK_SUBAGENT_TASK_ID, task_type: "local_agent" },
7130+
{
7131+
task_id: OWN_WORK_SHELL_TASK_ID,
7132+
task_type: "local_bash",
7133+
description: "Run the UI journeys",
7134+
parent_task_id: OWN_WORK_SUBAGENT_TASK_ID,
7135+
},
7136+
],
7137+
uuid: "00000000-0000-4000-8000-000000001704",
7138+
session_id: WAKE_NATIVE_SESSION,
7139+
}),
7140+
);
7141+
7142+
yield* Queue.offer(
7143+
harness.sdkMessages,
7144+
ownWorkSubagentNotification("00000000-0000-4000-8000-000000001705", OWN_WORK_INTERIM_SUMMARY),
7145+
);
7146+
yield* awaitUntil(
7147+
() => harness.continuationRequests.length === 1,
7148+
"interim completion continuation request",
7149+
);
7150+
yield* harness.offerAndWait(
7151+
makeResultFrame({
7152+
uuid: "00000000-0000-4000-8000-000000001706",
7153+
result: "The subagent is waiting on its UI journeys.",
7154+
}),
7155+
);
7156+
yield* harness.runtime.startTurn(
7157+
makeClaudeTestTurnInput({
7158+
threadId: harness.threadId,
7159+
providerThread: harness.providerThread,
7160+
now,
7161+
attemptId: RunAttemptId.make("attempt-claude-own-work-2"),
7162+
text: "Background task completed.",
7163+
attachments: [],
7164+
providerTurnOrdinal: 2,
7165+
messageCreatedBy: "agent",
7166+
messageCreationSource: "provider",
7167+
}),
7168+
);
7169+
yield* awaitUntil(() => harness.terminalEvents().length === 2, "continuation terminal");
7170+
});
7171+
7172+
it.effect("keeps a subagent running while its own background work outlives its turn", () =>
7173+
Effect.scoped(
7174+
Effect.gen(function* () {
7175+
const FINAL_SUMMARY = "OWN_BACKGROUND_WORK_DONE";
7176+
const harness = yield* makeWakeHarness;
7177+
const now = yield* DateTime.now;
7178+
yield* runOwnWorkSubagentToInterimCompletion(harness);
7179+
7180+
// The interim completion leaves the subagent running, says why, and
7181+
// keeps its interim answer.
7182+
const interim = ownWorkSubagentEvents(harness.events).at(-1)?.subagent;
7183+
assert.equal(interim?.status, "running");
7184+
assert.equal(interim?.progress, "Waiting for its background work");
7185+
assert.equal(interim?.result, OWN_WORK_INTERIM_SUMMARY);
7186+
assert.isFalse(
7187+
ownWorkSubagentEvents(harness.events).some(
7188+
(event) => event.subagent.status === "completed",
7189+
),
7190+
);
7191+
assert.isTrue(yield* harness.hasPendingBackgroundWork);
7192+
7193+
// The shell finishes and Claude resumes the subagent under the same
7194+
// task id and tool_use_id; its next completion is the final one.
7195+
yield* harness.offerAndWait(ownWorkShellNotification);
7196+
yield* harness.offerAndWait(
7197+
ownWorkSubagentStarted(
7198+
"00000000-0000-4000-8000-000000001709",
7199+
"<task-notification>\n<task-id>shell-own-background-work</task-id>\n</task-notification>",
7200+
),
7201+
);
7202+
yield* Queue.offer(
7203+
harness.sdkMessages,
7204+
ownWorkSubagentNotification("00000000-0000-4000-8000-000000001710", FINAL_SUMMARY),
7205+
);
7206+
yield* awaitUntil(
7207+
() => harness.continuationRequests.length === 2,
7208+
"final completion continuation request",
7209+
);
7210+
assert.equal(harness.continuationRequests[1]?.detail, FINAL_SUMMARY);
7211+
yield* harness.offerAndWait(
7212+
makeResultFrame({
7213+
uuid: "00000000-0000-4000-8000-000000001711",
7214+
result: "The subagent finished.",
7215+
}),
7216+
);
7217+
yield* harness.runtime.startTurn(
7218+
makeClaudeTestTurnInput({
7219+
threadId: harness.threadId,
7220+
providerThread: harness.providerThread,
7221+
now,
7222+
attemptId: RunAttemptId.make("attempt-claude-own-work-3"),
7223+
text: "Background task completed.",
7224+
attachments: [],
7225+
providerTurnOrdinal: 3,
7226+
messageCreatedBy: "agent",
7227+
messageCreationSource: "provider",
7228+
}),
7229+
);
7230+
yield* awaitUntil(() => harness.terminalEvents().length === 3, "final terminal");
7231+
7232+
const statuses = ownWorkSubagentEvents(harness.events).map(
7233+
(event) => event.subagent.status,
7234+
);
7235+
assert.equal(statuses.indexOf("completed"), statuses.length - 1);
7236+
const final = ownWorkSubagentEvents(harness.events).at(-1)?.subagent;
7237+
assert.equal(final?.result, FINAL_SUMMARY);
7238+
assert.isUndefined(final?.progress);
7239+
// It never settled, so the launch run that tracks it still owns it
7240+
// and receives its end.
7241+
assert.isTrue(
7242+
ownWorkSubagentEvents(harness.events).every(
7243+
(event) => event.subagent.runId === "run-attempt-claude-own-work-1",
7244+
),
7245+
);
7246+
assert.isFalse(yield* harness.hasPendingBackgroundWork);
7247+
}).pipe(Effect.provide(Layer.merge(IdAllocator.layer, NodeServices.layer))),
7248+
),
7249+
);
7250+
7251+
it.effect("moves a resumed subagent to the draining run when its launch run failed", () =>
7252+
Effect.scoped(
7253+
Effect.gen(function* () {
7254+
const harness = yield* makeWakeHarness;
7255+
const now = yield* DateTime.now;
7256+
yield* runOwnWorkSubagentToInterimCompletion(harness, { launchTurnFails: true });
7257+
assert.equal(harness.terminalEvents()[0]?.status, "failed");
7258+
assert.equal(ownWorkSubagentEvents(harness.events).at(-1)?.subagent.status, "running");
7259+
7260+
// The failed launch run stopped ingesting, so the resume must not stay
7261+
// on it: the draining run takes the subagent, as for any reopen.
7262+
yield* harness.offerAndWait(ownWorkShellNotification);
7263+
yield* harness.offerAndWait(
7264+
ownWorkSubagentStarted("00000000-0000-4000-8000-000000001714", "Resume."),
7265+
);
7266+
yield* Queue.offer(
7267+
harness.sdkMessages,
7268+
ownWorkSubagentNotification("00000000-0000-4000-8000-000000001715", "DONE"),
7269+
);
7270+
yield* awaitUntil(
7271+
() => harness.continuationRequests.length === 2,
7272+
"final completion continuation request",
7273+
);
7274+
yield* harness.offerAndWait(
7275+
makeResultFrame({ uuid: "00000000-0000-4000-8000-000000001716", result: "Done." }),
7276+
);
7277+
yield* harness.runtime.startTurn(
7278+
makeClaudeTestTurnInput({
7279+
threadId: harness.threadId,
7280+
providerThread: harness.providerThread,
7281+
now,
7282+
attemptId: RunAttemptId.make("attempt-claude-own-work-5"),
7283+
text: "Background task completed.",
7284+
attachments: [],
7285+
providerTurnOrdinal: 3,
7286+
messageCreatedBy: "agent",
7287+
messageCreationSource: "provider",
7288+
}),
7289+
);
7290+
yield* awaitUntil(() => harness.terminalEvents().length === 3, "final terminal");
7291+
const final = ownWorkSubagentEvents(harness.events).at(-1)?.subagent;
7292+
assert.equal(final?.status, "completed");
7293+
assert.equal(final?.runId, "run-attempt-claude-own-work-5");
7294+
}).pipe(Effect.provide(Layer.merge(IdAllocator.layer, NodeServices.layer))),
7295+
),
7296+
);
7297+
7298+
it.effect("settles a subagent whose own background work ends without resuming it", () =>
7299+
Effect.scoped(
7300+
Effect.gen(function* () {
7301+
const harness = yield* makeWakeHarness;
7302+
const now = yield* DateTime.now;
7303+
yield* runOwnWorkSubagentToInterimCompletion(harness);
7304+
assert.equal(ownWorkSubagentEvents(harness.events).at(-1)?.subagent.status, "running");
7305+
7306+
// The shell ends, and Claude never resumes the subagent.
7307+
yield* harness.offerAndWait(ownWorkShellNotification);
7308+
yield* harness.offerAndWait(
7309+
claudeSdkFrame({
7310+
type: "system",
7311+
subtype: "background_tasks_changed",
7312+
tasks: [],
7313+
uuid: "00000000-0000-4000-8000-000000001712",
7314+
session_id: WAKE_NATIVE_SESSION,
7315+
}),
7316+
);
7317+
assert.equal(ownWorkSubagentEvents(harness.events).at(-1)?.subagent.status, "running");
7318+
// Nothing runs anymore, so it no longer pins the session or blocks a
7319+
// model change.
7320+
assert.isFalse(yield* harness.hasPendingBackgroundWork);
7321+
7322+
// The next turn settles it with its interim result.
7323+
yield* harness.runtime.startTurn(
7324+
makeClaudeTestTurnInput({
7325+
threadId: harness.threadId,
7326+
providerThread: harness.providerThread,
7327+
now,
7328+
attemptId: RunAttemptId.make("attempt-claude-own-work-4"),
7329+
text: "Any news?",
7330+
attachments: [],
7331+
providerTurnOrdinal: 3,
7332+
}),
7333+
);
7334+
yield* awaitUntil(
7335+
() => ownWorkSubagentEvents(harness.events).at(-1)?.subagent.status === "completed",
7336+
"subagent settled",
7337+
);
7338+
assert.equal(
7339+
ownWorkSubagentEvents(harness.events).at(-1)?.subagent.result,
7340+
OWN_WORK_INTERIM_SUMMARY,
7341+
);
7342+
yield* Queue.offer(
7343+
harness.sdkMessages,
7344+
makeResultFrame({
7345+
uuid: "00000000-0000-4000-8000-000000001713",
7346+
result: "Nothing new.",
7347+
}),
7348+
);
7349+
yield* awaitUntil(() => harness.terminalEvents().length === 3, "user turn terminal");
7350+
assert.isFalse(yield* harness.hasPendingBackgroundWork);
7351+
}).pipe(Effect.provide(Layer.merge(IdAllocator.layer, NodeServices.layer))),
7352+
),
7353+
);
7354+
70187355
it.effect("resets Waiting roster and wake eligibility when the CLI process is replaced", () =>
70197356
Effect.scoped(
70207357
Effect.gen(function* () {

0 commit comments

Comments
 (0)