fix(eve): complete background task lifecycle routing

.changeset/remote-create-operation-id.md

@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Make subagent dispatch replay-safe. Remote create-session requests now carry a replay-stable `operationId`, and the built-in `POST /eve/v1/session` route returns the child it already created for that operation instead of starting a second one. A replayed local start adopts the child holding its deterministic continuation token rather than reporting a start failure.

.changeset/task-usage-retention.md

@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Background task terminal snapshots now retain the child's reported token usage instead of dropping it at the task wire. Accounting is unchanged: background children get a best-effort budget capped at dispatch time, and aggregate spend across sequential dispatches is not yet reserved against the parent's session limits.

.changeset/tasks-experimental-subagents.md

@@ -2,4 +2,4 @@
 "eve": patch
 ---
 
-Add experimental background tasks for subagents. With `experimental.tasks` on the root agent, subagent calls return a task receipt immediately instead of blocking the turn, and the model manages the delegated work with the new `task_peek`, `task_await`, `task_cancel`, `task_send`, and `task_sleep` tools. Terminal results and input requests wake the parent through the normal session delivery path. Without the flag, nothing changes.
+Add experimental background tasks for subagents. Child input requests surface on the parent session and client responses route directly back without a parent model turn; `task_send` continues a finished task, and one child session owns at most one nonterminal task. Without `experimental.tasks`, nothing changes.

docs/channels/eve.mdx

@@ -41,6 +41,14 @@ curl -X POST https://<deployment>/eve/v1/session \
 # {"continuationToken":"eve:7f3c...","ok":true,"sessionId":"ses_01h..."}
 ```
 
+A caller that may retry a create request can pass its own `operationId` to get create-once semantics. eve derives that operation's continuation token from the id and the authenticated caller, so a retry with the same id returns the session it already created instead of starting a second one, and one caller's id can never address another caller's session. The guarantee holds while that session is still resumable; eve keeps no record of operations whose session has already ended.
+
+```bash
+curl -X POST https://<deployment>/eve/v1/session \
+  -H "Content-Type: application/json" \
+  -d '{"message":"What is the weather in Paris?","operationId":"order-4213-research"}'
+```
+
 Stream that session's events as newline-delimited JSON (`application/x-ndjson; charset=utf-8`), one event object per line:
 
 ```bash

docs/tools/human-in-the-loop.md

@@ -109,6 +109,8 @@ semantics.
 
 The run picks back up exactly where it parked. Because the pause is durable, nothing is held in memory while it waits — the process can restart and the parked turn survives.
 
+When a background subagent requests input, eve emits the same `input.requested` event on its parent session. Answering through that parent session routes the response directly to the blocked child without invoking the parent model.
+
 For approval requests, unrelated follow-up text does not deny the tool call. eve keeps the approval pending and holds that text until the approval is answered, then replays it as the next message in the session.
 
 See [Sessions, runs & streaming](/docs/concepts/sessions-runs-and-streaming) for the full event and resume contract that this builds on.

packages/eve/src/channel/routes.ts

@@ -95,9 +95,11 @@ type BaseSendOptions = {
   continuationToken: string;
   /**
    * `"resume"` requires an active session and propagates a typed no-active-session
-   * error. `"resume-or-start"` preserves the default channel behavior.
+   * error. `"create-once"` adopts an existing or concurrently-created owner
+   * without delivering the duplicate input. `"resume-or-start"` preserves the
+   * default channel behavior.
    */
-  intent?: "resume" | "resume-or-start";
+  intent?: "create-once" | "resume" | "resume-or-start";
   /**
    * The original (top-level) caller's auth for a newly started session,
    * becoming `session.auth.initiator`. Defaults to {@link auth} when omitted

packages/eve/src/channel/send.test.ts

@@ -144,6 +144,50 @@ describe("createSendFn", () => {
     expect(runtime.dispatchContinuation).toHaveBeenCalledTimes(2);
   });
 
+  it("adopts a concurrent create-once winner without delivering duplicate input", async () => {
+    const runtime = createRuntime();
+    vi.mocked(runtime.createSession).mockRejectedValue(
+      new RuntimeSessionOwnershipConflictError({
+        continuationToken: "test:token",
+        ownerSessionId: "winner",
+        sessionId: "loser",
+      }),
+    );
+    vi.mocked(runtime.resolveContinuation).mockResolvedValue(undefined);
+
+    await expect(
+      createSendFn(
+        runtime,
+        ADAPTER,
+        "test",
+      )("hello", {
+        auth: null,
+        continuationToken: "token",
+        intent: "create-once",
+      }),
+    ).resolves.toMatchObject({ id: "winner" });
+    expect(runtime.dispatchContinuation).not.toHaveBeenCalled();
+  });
+
+  it("adopts an existing create-once owner without delivering duplicate input", async () => {
+    const runtime = createRuntime();
+    vi.mocked(runtime.resolveContinuation).mockResolvedValue({ sessionId: "winner" });
+
+    await expect(
+      createSendFn(
+        runtime,
+        ADAPTER,
+        "test",
+      )("hello", {
+        auth: null,
+        continuationToken: "token",
+        intent: "create-once",
+      }),
+    ).resolves.toMatchObject({ id: "winner" });
+    expect(runtime.dispatchContinuation).not.toHaveBeenCalled();
+    expect(runtime.createSession).not.toHaveBeenCalled();
+  });
+
   it("forwards the turn caller on the session command", async () => {
     const runtime = createRuntime({ sessionId: "existing-session-id", status: "accepted" });
     const caller = {

packages/eve/src/channel/send.ts

@@ -55,7 +55,11 @@ export function createSendFn<TState = undefined>(
         : undefined;
     };
 
-    const existing = await dispatch();
+    const existingOwner = async (): Promise<Session | undefined> => {
+      const owner = await runtime.resolveContinuation(continuationToken);
+      return owner === undefined ? undefined : createSession(owner.sessionId, rawToken, runtime);
+    };
+    const existing = intent === "create-once" ? await existingOwner() : await dispatch();
     if (existing !== undefined) return existing;
     if (intent === "resume") throw new RuntimeNoActiveSessionError(continuationToken);
 
@@ -91,6 +95,9 @@ export function createSendFn<TState = undefined>(
       return createSession(handle.sessionId, rawToken, runtime);
     } catch (error) {
       if (!isRuntimeSessionOwnershipConflictError(error)) throw error;
+      if (intent === "create-once") {
+        return createSession(error.ownerSessionId, rawToken, runtime);
+      }
       const winner = await dispatch();
       if (winner !== undefined) return winner;
       throw error;

packages/eve/src/channel/session-callback.ts

@@ -19,6 +19,7 @@ const sessionCallbackSchema = z
   .object({
     callId: z.string().min(1),
     subagentName: z.string().min(1),
+    taskId: z.string().min(1).optional(),
     token: z.string().min(1),
     url: z.string().min(1),
   })

packages/eve/src/channel/types.ts

@@ -22,6 +22,8 @@ export type RunSessionLimits = Pick<
 /** Identifies the session turn to cancel. */
 export interface CancelTurnInput {
   readonly sessionId: string;
+  /** Framework task whose queued child deliveries should be discarded. */
+  readonly taskId?: string;
   /** Limits the request to the turn the caller observed. */
   readonly turnId?: string;
 }
@@ -151,6 +153,8 @@ export type EventEmitFn = (event: UnstampedMessageStreamEvent) => Promise<void>;
 export interface TurnCaller {
   readonly callId: string;
   readonly subagentName: string;
+  /** Present when this turn is the executor for a durable background task. */
+  readonly taskId?: string;
   readonly replyTo:
     | { readonly kind: "hook"; readonly token: string }
     | { readonly kind: "callback"; readonly url: string };
@@ -173,6 +177,11 @@ export interface DeliverPayload {
   readonly message?: string | UserContent;
   readonly context?: readonly string[];
   readonly outputSchema?: JsonObject;
+  /** Framework-only task HITL envelopes consumed before adapter/model delivery. */
+  readonly taskInputRequests?: readonly {
+    readonly hookPayload: SubagentInputRequestHookPayload;
+    readonly taskId: string;
+  }[];
   readonly [key: string]: unknown;
 }
 
@@ -184,8 +193,10 @@ export type SessionCommand =
       readonly kind: "send";
       readonly payload: DeliverPayload;
       readonly requestId?: string;
+      /** Replay-stable identity for one task-owned child delivery. */
+      readonly taskDeliveryId?: string;
     }
-  | { readonly kind: "cancel"; readonly turnId?: string }
+  | { readonly kind: "cancel"; readonly taskId?: string; readonly turnId?: string }
   | { readonly kind: "compact" }
   | { readonly kind: "clear" }
   | { readonly kind: "reset"; readonly reason?: string };
@@ -235,6 +246,7 @@ export interface DeliverHookPayload {
   readonly caller?: TurnCaller;
   /** Inbound channel request id used only for workflow attributes. */
   readonly requestId?: string;
+  readonly taskDeliveryId?: string;
   readonly kind: "deliver";
   readonly payloads: readonly DeliverPayload[];
 }
@@ -339,6 +351,7 @@ export type HookPayload =
 export interface SessionCallback {
   readonly callId: string;
   readonly subagentName: string;
+  readonly taskId?: string;
   readonly token: string;
   readonly url: string;
 }

packages/eve/src/cli/dev/tui/tool-presentation.test.ts

@@ -178,7 +178,6 @@ describe("presentTool", () => {
       grep: { pattern: "useEve" },
       load_skill: { skill: "commit" },
       read_file: { filePath: "/workspace/a.ts" },
-      task_await: { taskIds: ["task_abc"] },
       task_cancel: { taskIds: ["task_abc"] },
       task_peek: { taskIds: ["task_abc"] },
       task_send: { message: "Continue with the next region.", taskId: "task_abc" },

packages/eve/src/cli/dev/tui/tool-presentation.ts

@@ -123,14 +123,6 @@ const BUILTIN_TOOL_COPY: Readonly<Record<string, BuiltinToolCopy>> = {
     singularNoun: "file",
     pluralNoun: "files",
   },
-  task_await: {
-    verb: "Await",
-    pastVerb: "Awaited",
-    argKey: "taskIds",
-    extractItem: taskIdsArg,
-    singularNoun: "task",
-    pluralNoun: "tasks",
-  },
   task_cancel: {
     verb: "Cancel",
     pastVerb: "Cancelled",

packages/eve/src/execution/agent-handle-dispatch.ts

@@ -32,6 +32,7 @@ import { createWorkflowCallbackUrl } from "#execution/workflow-callback-url.js";
 import { createLogger, logError } from "#internal/logging.js";
 import { createEveCallbackRoutePath } from "#protocol/routes.js";
 import { err, ok, type Result } from "#shared/result.js";
+import { readTaskIdFromCommandToken } from "#tasks/task-id.js";
 
 const log = createLogger("execution.agent-handle-dispatch");
 
@@ -255,6 +256,7 @@ async function deliverToAgentHandle(input: {
         callback: {
           callId: action.callId,
           subagentName: identity.name,
+          taskId: readTaskIdFromCommandToken(input.parentToken),
           token: input.parentToken,
           url: createWorkflowCallbackUrl(
             address.callbackBaseUrl,
@@ -287,6 +289,7 @@ async function deliverToAgentHandle(input: {
           callId: action.callId,
           replyTo: { kind: "hook", token: input.parentToken },
           subagentName: identity.name,
+          taskId: readTaskIdFromCommandToken(input.parentToken),
         },
         kind: "send",
         payload: {

packages/eve/src/execution/delegated-parent-notification.test.ts

@@ -7,6 +7,7 @@ import { BundleKey, ChannelKey } from "#runtime/sessions/runtime-context-keys.js
 import { getCompiledRuntimeAgentBundle } from "#runtime/sessions/compiled-agent-cache.js";
 import {
   notifyDelegatedParentStep,
+  notifyTaskTurnStartedStep,
   notifyTurnCallerStep,
   resolveInitialTurnCallerStep,
 } from "#execution/delegated-parent-notification.js";
@@ -177,6 +178,46 @@ describe("turn caller notification", () => {
     expect(resumeHookMock).not.toHaveBeenCalled();
   });
 
+  it("binds a local task hook to the exact child turn before execution", async () => {
+    await notifyTaskTurnStartedStep({
+      caller: {
+        callId: "call-task",
+        replyTo: { kind: "hook", token: "task-token" },
+        subagentName: "research",
+        taskId: "task-1",
+      },
+      childSessionId: "child-session",
+      childTurnId: "turn_child_7",
+    });
+
+    expect(resumeHookMock).toHaveBeenCalledWith("task-token", {
+      childSessionId: "child-session",
+      childTurnId: "turn_child_7",
+      kind: "task-child-turn-started",
+      taskId: "task-1",
+    });
+  });
+
+  it("posts the same task turn identity through a remote callback", async () => {
+    await notifyTaskTurnStartedStep({
+      caller: {
+        callId: "call-task",
+        replyTo: { kind: "callback", url: "https://parent.example/eve/v1/callback/task-token" },
+        subagentName: "research",
+        taskId: "task-1",
+      },
+      childSessionId: "child-session",
+      childTurnId: "turn_child_7",
+    });
+
+    expect(JSON.parse(fetchMock.mock.calls[0]?.[1]?.body as string)).toMatchObject({
+      kind: "turn.started",
+      sessionId: "child-session",
+      taskId: "task-1",
+      turnId: "turn_child_7",
+    });
+  });
+
   it("uses the adapter state for the child's first settled turn", async () => {
     const serializedContext = createSerializedContext();
     const caller = await resolveInitialTurnCallerStep({ serializedContext });

packages/eve/src/execution/delegated-parent-notification.ts

@@ -22,6 +22,8 @@ import { parseJsonValue } from "#shared/json.js";
 import type { TokenUsage } from "#shared/token-usage.js";
 import { resumeHook } from "#internal/workflow/runtime.js";
 import { postSessionCallbackRequest } from "#execution/session-callback-request.js";
+import type { TaskInboundTurnStarted } from "#tasks/types.js";
+import { readTaskIdFromCommandToken } from "#tasks/task-id.js";
 
 const log = createLogger("execution.delegated-parent-notification");
 
@@ -129,6 +131,42 @@ export async function notifyTurnCallerStep(input: {
   await resumeSettledTurnHook(input.caller.replyTo.token, result);
 }
 
+/** Binds a durable task to the exact child turn before execution starts. */
+export async function notifyTaskTurnStartedStep(input: {
+  readonly caller: TurnCaller | undefined;
+  readonly childSessionId: string;
+  readonly childTurnId: string;
+}): Promise<void> {
+  "use step";
+
+  const taskId = input.caller?.taskId;
+  if (input.caller === undefined || taskId === undefined) return;
+  const payload: TaskInboundTurnStarted = {
+    childSessionId: input.childSessionId,
+    childTurnId: input.childTurnId,
+    kind: "task-child-turn-started",
+    taskId,
+  };
+  if (input.caller.replyTo.kind === "hook") {
+    await resumeHook(input.caller.replyTo.token, payload);
+    return;
+  }
+  const response = await postSessionCallbackRequest({
+    body: {
+      callId: input.caller.callId,
+      kind: "turn.started",
+      sessionId: input.childSessionId,
+      subagentName: input.caller.subagentName,
+      taskId,
+      turnId: input.childTurnId,
+    },
+    url: input.caller.replyTo.url,
+  });
+  if (!response.ok) {
+    throw new Error(`Task turn-start callback failed with HTTP ${response.status}.`);
+  }
+}
+
 function createSettledTurnResult(input: {
   readonly caller: TurnCaller;
   readonly lifecycle: AgentTurnOutcome["kind"];
@@ -193,6 +231,7 @@ export async function resolveInitialTurnCallerStep(input: {
       callId: parsed.callback.callId,
       replyTo: { kind: "callback", url: parsed.callback.url },
       subagentName: parsed.callback.subagentName,
+      taskId: parsed.callback.taskId ?? readTaskIdFromCommandToken(parsed.callback.token),
     };
   }
 
@@ -206,6 +245,7 @@ export async function resolveInitialTurnCallerStep(input: {
     callId: adapter.state.callId,
     replyTo: { kind: "hook", token: adapter.state.parentContinuationToken },
     subagentName: adapter.state.subagentName,
+    taskId: readTaskIdFromCommandToken(adapter.state.parentContinuationToken),
   };
 }