eve 0.67.2 → 0.69.0

package/docs/subagents/index.mdx

@@ -9,41 +9,13 @@ Use a subagent to run independent work in parallel, narrow the available tools,
 - Use a [declared local subagent](#declared-subagents) for a specialist with its own directory and authored capabilities, rather than inheriting the root's.
 - Use a [remote agent](./guides/remote-agents) to delegate to a separately deployed eve agent, with its own configuration and authentication.
 
-A subagent can finish a model turn while background tasks started in that turn are still running.
-That turn yields; its interim reply does not complete the caller's delegated task. Background work started by an earlier turn does not hold the reply, and a turn that ends with an error always answers the caller. If the child session expires, resets, or closes before replying, the delegated task fails and reports the usage accumulated since its previous settlement.
-After the nested tasks finish, the subagent resumes and returns its final result to
-the caller. This applies to root-agent copies, declared local subagents, and remote
-subagents. The subagent session remains available for later calls.
-
-## Completion batching
-
-Overlapping background work owned by a session forms a cohort. Tasks launched in
-later user turns join the open cohort while earlier work is still pending or its
-terminal results await delivery. With `taskDeliveryPolicy: "cohort"`, eve holds
-completion, failure, and cancellation notifications
-until every task in that cohort has completed, failed, or been cancelled, then
-delivers all outcomes together in one parent turn. Partial settlements
-do not invoke the parent model. Work started after the cohort settles forms a new
-cohort.
-
-New channel sessions default to `"auto"`; schedules default to `"cohort"`.
-Pass `taskDeliveryPolicy` to `send(...)` to select or update the session policy. See
-[Background task results](/docs/channels/overview#background-task-results).
-
-With `"auto"`, a terminal outcome can start a parent turn while other tasks are
-still running. The parent reports independently useful results and stays silent
-when a useful answer depends on unfinished tasks. Ready results may share a turn.
-The reporting context includes the whole cohort and every available output,
-including previously withheld results, for a later combined report.
-
-The setting applies to background tools and built-in, declared, and remote
-subagents owned by the session. Internal subagent sessions use `"cohort"` for
-background work they start.
-
-User messages, input requests, authorization events, failures, and cancellation
-are handled without waiting for the cohort. Child lifecycle events are processed
-before completion delivery so usage accounting and handle cleanup stay ordered.
-To follow work in progress, subscribe to the child session streams.
+Every subagent call runs as a [task](./tools/tasks). The call returns a
+receipt naming the task's `taskId` right away, the child works while the parent continues, and the
+child's final reply for that turn arrives as the task's result. The parent's turn does not end while
+the task is working. If the child's turn fails, the call fails and the task ends. This applies to
+root-agent copies, declared local subagents, and remote subagents. The subagent session remains
+available for later calls with the same `taskId`. When an action must wait for a subagent's result,
+such as publishing only after a review, [run both from one workflow tool](./tools/tasks#order-work-that-depends-on-a-result).
 
 ## The built-in `agent` tool
 
@@ -51,12 +23,12 @@ The root session receives `agent` by default. The model calls it to delegate a t
 
 ```ts
 {
-  message: string;  // everything the child needs; it does not see the parent's history
-  agentId?: string; // continue or steer an existing child
+  message: string; // everything the child needs; it does not see the parent's history
+  taskId?: string; // continue an existing child
 }
 ```
 
-The copy uses the root's instructions, connections, auth, and sandbox. It receives the same tools except for the root-only `agent`, and starts with fresh conversation history and fresh state. Its file writes are immediately visible to the root. The built-in `agent` always runs in the background and needs no configuration: each call returns `{ status: "working", taskId, agentId }`, then task notifications wake the parent with completion, failure, or cancellation. Give parallel children non-overlapping write scopes.
+The copy uses the root's instructions, connections, auth, and sandbox. It receives the same tools except for the root-only `agent`, and starts with fresh conversation history and fresh state. Its file writes are immediately visible to the root. The built-in `agent` needs no configuration. Each call starts or continues a task whose result is the child's reply, so several children can work at once, whether the model starts them in one response or across several. Give parallel children non-overlapping write scopes.
 
 `agent` is intentionally root-only. Copies created by it cannot call `agent`, and declared subagents never receive the built-in tool. If a stale or forced recursive call reaches execution, eve rejects it instead of starting another child session.
 
@@ -102,9 +74,7 @@ export default defineAgent({
 
 The parent can alternatively export `disableTool()` from a same-named tool path, such as `agent/tools/researcher.ts`. This suppresses the derived model tool without removing `researcher` from the workflow invocation registry. A same-named authored tool replaces the model-facing surface while the workflow can still call the underlying subagent with `ctx.agent("researcher", ...)`.
 
-Every declared local or remote subagent runs as a durable background task: the call returns `{ status: "working", taskId, agentId }` immediately, then task notifications wake the parent with completion, failure, or cancellation. Human input requests surface separately on the parent session.
-
-`task_cancel` is available to sessions that own background tasks, including a child that starts nested background work. Cancelling a delegated agent task also requests cancellation of its child's nested background tasks, even after that child's model turn has yielded. The child does not start another model turn for notifications from that cancelled work. This applies to self, local, and remote delegation. The calling model receives the cancellation receipt in the `task_cancel` result; a later report of that same outcome does not start another model turn.
+A declared local or remote subagent call returns a receipt, and the child's reply arrives as the task's result. Human input requests from the child surface on the parent session while the task works. `task_cancel` with the task's `taskId` cancels the child's current turn, and so does cancelling the calling turn.
 
 A mounted extension can also contribute declared subagents from `extension/subagents/`. The mount namespace prefixes the subagent visible to the consuming agent node: mounting an extension as `crm` exposes its `reviewer` subagent as `crm__reviewer`. The contributed subagent keeps its own isolated tools, connections, skills, hooks, instructions, sandbox, and nested subagents, and its modules can read configuration from the extension handle. See [Extensions](./extensions#add-a-subagent) for the authoring and override behavior.
 
@@ -238,7 +208,7 @@ The root built-in `agent` tool is the exception. Its children reuse the root's s
 
 ## What the parent sees
 
-eve lowers every tool-enabled subagent visible to the current agent (the root built-in copy, declared, or [remote](./guides/remote-agents)) into a model-visible tool with the same `{ message, agentId? }` shape. The parent packs `message` with everything the child needs, since the child never sees the parent's history. To require structured output from a child, call it from an authored workflow tool with [`ctx.agent(name, { message, outputSchema })`](./tools/workflows); the schema applies to that turn, and the child remains available for follow-up messages afterward.
+eve lowers every tool-enabled subagent visible to the current agent (the root built-in copy, declared, or [remote](./guides/remote-agents)) into a model-visible tool with the same `{ message, taskId? }` shape. The parent packs `message` with everything the child needs, since the child never sees the parent's history. To require structured output from a child, open a session with it from an authored workflow tool with [`ctx.agent(name)`](./tools/workflows#delegate-work-ctxagent) and pass `outputSchema` to `send()`; the schema applies to that turn, and the session accepts follow-up messages until the workflow run finishes.
 
 Declared subagents can call nested subagents defined under their own directories. eve does not apply a separate depth limit; nesting ends where the authored directory tree ends. The built-in `agent` follows the stricter root-only rule above, so `limits.maxSubagentDepth` no longer exists.
 
@@ -248,36 +218,34 @@ A directly declared subagent's tool name is the bare path-derived name, with no
 
 ```ts
 {
-  message: string;  // all context the child needs; it never sees the parent's history
-  agentId?: string; // continue or steer an existing child
+  message: string; // all context the child needs; it never sees the parent's history
+  taskId?: string; // continue an existing child
 }
 ```
 
+The tool's description is the subagent's `description` followed by a sentence telling the model that the agent does not see the conversation and that `taskId` continues an agent task.
+
 By default, a subagent named `researcher` collides with an authored tool named `researcher`. Set the subagent's `tool` to `false` when the authored tool intentionally wraps that subagent; the authored tool becomes the model-facing capability while `ctx.agent("researcher", ...)` continues to address the child. A same-named `disableTool()` removes the model-facing capability entirely. Other static and active dynamic collisions remain errors.
 
 Do not rely on subagent delegation by itself as an approval boundary. Put sensitive tools behind `approval`, connection approval, route/session authorization, or other controls wherever those tools can be called.
 
-Each delegated subagent spins up its own child session and stream. The parent stream carries the control-plane events `subagent.called` and `subagent.completed`, plus interactive `input.requested`, `authorization.required`, and `authorization.completed` events proxied from descendants so the root channel can prompt the user. To follow the child's other progress, pass the `subagent.called` event to [`session.streamSubagent()`](./guides/client/streaming#follow-a-subagent) on a client session attached to the parent. It reads `subagent.called.data.childStreamPath`: the child's own session stream for a local child, or a parent-origin proxy for a remote child, which the parent authenticates to the remote deployment.
+Each delegated subagent spins up its own child session and stream. The parent stream carries the call's `task.started` and `task.settled` events, `agent.started` when the child session opens, plus interactive `input.requested`, `authorization.required`, and `authorization.completed` events proxied from descendants so the root channel can prompt the user. The parent emits `input.resolved` when it routes an answer back down to the descendant that asked. `task.settled` carries the child's reply as `output` when the call completes, or `error.message` when it fails, along with the same tool `name` and `kind: "agent"` as the call's `task.started`. To follow the child's other progress, pass the `agent.started` event to [`session.agent()`](./guides/client/streaming#follow-a-subagent) on a client session attached to the parent and follow the child with `stream()`. It reads `agent.started.data.streamPath`: the child's own session stream for a local child, or a parent-origin proxy for a remote child, which the parent authenticates to the remote deployment.
 
-Both blocking and background invocations emit `subagent.called` after dispatch and `subagent.completed` after the parent records successful completion. Completion carries the actual output and identifies the same invocation by `callId`; the child session can remain available for reuse. A background working receipt is returned as an `action.result` tool output and does not emit completion. Background completion events do not wait for the cohort report. Failure and cancellation are not successful completion; task notifications retain those outcomes.
+`agent.started` carries the `callId` and `turnId` of the call that opened the session, the call's `taskId`, the agent `name`, and the child's `sessionId`. Later calls with the same `taskId` reach the same session and do not announce it again, so match a child to its calls by `taskId`. A session an authored workflow tool opens with `ctx.agent` is announced the same way, with its `taskId` only when the workflow tool call runs as a task.
 
-Channels with activity reporting attribute the backing agent's tool activity to its background task. Local and remote subagents share the task's progress item rather than adding a separate agent item. Continuing or steering a child with `agentId` attaches its new activity to the new task; the previous task keeps its completed or cancelled status. This applies to the built-in `agent` and declared subagent tools, not to child invocations inside custom workflow tools. Activity reporting is best-effort and does not change task execution or result delivery.
+Channels with activity reporting show a subagent's tool activity beneath that subagent's progress item. Activity reporting is best-effort and does not change execution or result delivery.
 
-A background task that was already admitted survives cancellation of the turn that started it; background work that has not yet been admitted is rejected with the cancelled step. Use `task_cancel` to stop an admitted task. Cancellation delivers the task's final notification to an active parent even if the task must be stopped forcibly. Parent-session finalization cancels remaining live tasks.
-
-Subagent model calls automatically retry classified transient provider failures, including overload errors delivered after a stream starts. eve makes at most three fresh model-call attempts, repeating only the current uncommitted call by default so completed earlier Workflow steps, tool results, and sandbox work remain available to the child. A declared subagent that opts into [Workflow checkpoint batching](./agent-config#workflow-checkpoint-batching) can instead repeat the uncommitted calls and inline tool executions in its current batch. Other recoverable task errors fall back to Workflow's durable step retry from the last committed session snapshot. Exhausting the transient model-call attempts or the dedicated empty-response reissue returns one failed task result instead of stacking both retry budgets; terminal errors fail immediately.
+Subagent model calls automatically retry classified transient provider failures, including overload errors delivered after a stream starts. eve makes at most three fresh model-call attempts, repeating only the current uncommitted call by default so completed earlier Workflow steps, tool results, and sandbox work remain available to the child. A declared subagent that opts into [Workflow checkpoint batching](./agent-config#workflow-checkpoint-batching) can instead repeat the uncommitted calls and inline tool executions in its current batch. Other recoverable errors fall back to Workflow's durable step retry from the last committed session snapshot. Exhausting the transient model-call attempts or the dedicated empty-response reissue returns one failed result instead of stacking both retry budgets; terminal errors fail immediately.
 
 ## Agent messaging
 
-A child parks after answering instead of terminating, keeping its session and conversation history alive. A failed child turn can also leave the child parked — its latest status shows the error and the parent may message it again. Pass a parked child's `agentId` to the same subagent tool with a new `message` to continue that session. Omitting `agentId` (or passing an empty string or `null`) always starts a new child, and an `agentId` that matches no known agent falls back to starting a new child rather than failing. Passing a known `agentId` through a different subagent tool fails with `AGENT_MISMATCH`.
-
-To steer a running background child, call the same subagent tool with its `agentId` and the updated `message`. Before answer output or local tool execution begins, steering interrupts the child's pending model generation and applies the update in the same turn. Executing tools finish and checkpoint their results first; after answer output starts, steering waits for the next committed Workflow boundary. The receipt retains the same `agentId` and `taskId`; steering does not cancel the task, replace its completion callback, or undo tool side effects that have already occurred.
+A child parks after answering instead of terminating, keeping its session and conversation history alive. Pass the task's `taskId` to the same subagent tool with a new `message` to continue that session. Omitting `taskId` always starts a new child. When a child's turn fails, the call fails and the task ends. A `taskId` that names no task of that subagent tool, including one that ended, fails with `UNKNOWN_TASK`. Any later turn can continue the child, and each continuation runs with the auth of the caller that sends it.
 
-A child that is still starting, or is owned by a blocking workflow invocation rather than an admitted background task, continues to return `AGENT_BUSY`. Delivery failures are reported to the caller; eve does not start a replacement child session to hide them.
+A call with the `taskId` of a child that is still working joins the child's current turn, and that turn's final reply settles both calls. If the turn ends before the child reads the message, the message starts the child's next turn, and that turn's reply settles both calls. Use it to correct or add to work in progress. `task_cancel` with the task's `taskId` cancels the child's current turn and keeps its conversation, so a later call with the same `taskId` continues where it left off.
 
-Whenever the set of parked (resumable) children changes, eve appends a framework-injected note to the conversation — labeled `[Agents]` and carrying an `<agents>` block — listing each child's `agentId`, name, and latest status. The static system prompt tells the model the note is injected by eve, not written by the user. The note is appended only when the listing changes (an append-only design that preserves the provider prompt cache), the most recent note is authoritative, and children that are starting or running do not appear until they park again.
+eve adds a framework-injected `[Tasks]` note to the conversation that lists the working and idle tasks by `taskId` and tool, so the model can find a child to continue. See [Tasks](./tools/tasks) for how the model waits for, corrects, and cancels agent tasks.
 
-The parent holds agent handles only for its session lifetime. When the parent session ends, eve terminates local children and sends authenticated reset requests for remote children. Remote reset is best-effort: an unreachable deployment may retain the parked child until its own session deadline. For [remote agents](./guides/remote-agents), upgrade both deployments before relying on continuation or reset behavior introduced by a newer eve version.
+The parent holds each child for the life of the task's run, which lasts until the parent session ends. Then eve resets local children and sends authenticated reset requests for remote children. Remote reset is best-effort: an unreachable deployment may retain the parked child until its own session deadline. For [remote agents](./guides/remote-agents), upgrade both deployments before relying on continuation or reset behavior introduced by a newer eve version.
 
 ## When to split
 

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

@@ -9,11 +9,13 @@ Human-in-the-loop (HITL) is any point where the agent durably pauses and waits f
 - **Approvals** — a tool policy allows, denies, or pauses a call for a person to review. The agent decides to call the tool; the policy decides whether it runs automatically or needs a human decision.
 - **Questions** — the agent itself asks the user a clarifying question or a choice mid-turn, and parks until they answer.
 
-Either way the run parks at `session.waiting`, durably, for as long as it takes — seconds or days — and picks back up exactly where it left off once the answer arrives. Channels render the request for you.
+An approval ends the turn and the session parks at `session.waiting`. A question keeps the turn open, and the stream reports `turn.waiting`. Either way the run waits durably, for as long as it takes — seconds or days — and picks back up exactly where it left off once the answer arrives. Channels render the request for you.
 
 ## Approvals
 
-Approval is a property of a [tool](/docs/tools) that gates it before it runs. The policy can decide automatically or pause for a person. Set `approval` with the helpers from `eve/tools/approval`:
+Approval is a property of a [tool](/docs/tools) that gates it before it runs. This includes [workflow tools](/docs/tools/workflows): a call waiting for approval does not start its workflow, and a call denied by a policy or person never runs. Other calls from the same model response that do not require approval can proceed while it waits.
+
+The policy can decide automatically or pause for a person. Set `approval` with the helpers from `eve/tools/approval`:
 
 ```ts title="agent/tools/refund_charge.ts"
 import { defineTool } from "eve/tools";
@@ -82,7 +84,7 @@ Gating a side effect on approval is also how you make non-idempotent work safe a
 
 ### Authorizing approval responses
 
-You may also define an approval response policy that decides whether the authenticated person who selects **Approve** may approve that specific call:
+You may also define an approval response policy that decides whether the authenticated person who selects **Approve** or **Cancel** may settle that specific call:
 
 ```ts title="agent/tools/refund_charge.ts"
 import { defineTool } from "eve/tools";
@@ -94,11 +96,11 @@ export default defineTool({
   inputSchema: z.object({ chargeId: z.string() }),
   approval: {
     request: always(),
-    response: ({ responder, request, response, session, auth }) => {
+    response: ({ request, response, session, auth }) => {
       // The Slack channel authenticates the responder and includes the workspace and user IDs.
       // Larger apps can look up approver membership here instead.
       const approvers = ["slack:T012AB3CD:U045EF6GH", "slack:T012AB3CD:U078JK9LM"];
-      const canApprove = approvers.includes(responder.principalId);
+      const canApprove = approvers.includes(response.principal.principalId);
 
       return canApprove
         ? { status: "allowed" }
@@ -113,13 +115,46 @@ export default defineTool({
 
 The `response` policy receives:
 
-- `responder`: the authenticated principal that submitted the response, including its `principalId`, `principalType`, `authenticator`, and `attributes`. Your route or channel supplies this identity.
-- `request`: the stable `requestId`, `callId`, `toolName`, and typed `toolInput` for the call being approved.
-- `response`: the submitted decision. Response policies run for approval, so its current value is `{ decision: "approve" }`.
+- `request`: the stable `requestId`, `callId`, `toolName`, and typed `toolInput` for the call being approved, plus `principal`: the authenticated principal whose turn requested the call, or `null` when that caller was unauthenticated or anonymous. eve captures `request.principal` when the approval is requested, so it stays the same while other people continue the session.
+- `response`: the submitted `decision`, `"approve"` or `"cancel"`, plus `principal`: the authenticated principal that submitted it, including its `principalId`, `principalType`, `authenticator`, and `attributes`. Your route or channel supplies this identity. The policy runs for both decisions, so a responder it rejects can neither approve nor cancel the call.
 - `session`: read-only session identity and lineage: `id`, `initiator`, `parent`, and `turn`.
 - `auth`: narrow `getToken(provider, options?)` and `requireAuth(provider, options?)` capabilities bound to the responder. Use these when authorization depends on a provider identity or permission; an interactive provider flow parks durably and then retries the policy.
 
-Return `{ status: "allowed" }` to accept the approval. Return `{ status: "rejected", reason }` to leave the shared request pending so another eligible responder can approve it.
+Return `{ status: "allowed" }` to accept the decision. Return `{ status: "rejected", reason }` to leave the shared request pending so another eligible responder can settle it. When a policy only cares who approves, return `{ status: "allowed" }` for `cancel` so anyone can still dismiss the request.
+
+`session.initiator` is the person who started the session, and `request.principal` is the person who asked for this call. In a shared thread they can differ. Compare the full identity of `response.principal` with `request.principal` to let only the requester settle the call:
+
+```ts title="agent/tools/publish_release.ts"
+import { defineTool } from "eve/tools";
+import type { SessionAuthContext } from "eve/context";
+import { always } from "eve/tools/approval";
+import { z } from "zod";
+
+function samePrincipal(a: SessionAuthContext, b: SessionAuthContext): boolean {
+  return (
+    a.authenticator === b.authenticator &&
+    a.issuer === b.issuer &&
+    a.principalType === b.principalType &&
+    a.principalId === b.principalId
+  );
+}
+
+export default defineTool({
+  description: "Publish a release.",
+  inputSchema: z.object({ version: z.string() }),
+  approval: {
+    request: always(),
+    // `request.principal` is null for an unauthenticated or anonymous caller, so no one matches it.
+    response: ({ request, response }) =>
+      request.principal !== null && samePrincipal(response.principal, request.principal)
+        ? { status: "allowed" }
+        : { status: "rejected", reason: "Only the person who asked for this release can respond." },
+  },
+  async execute(input) {
+    return publish(input);
+  },
+});
+```
 
 When a response is refused without starting a turn, the session returns to `session.waiting`. The client finishes the submission and keeps the approval prompt answerable. Submitting an answer does not confirm approval: `approval.settled` or `input.resolved` records the server's decision. You can inspect `approval.candidate` events for the response policy's refusal reason.
 
@@ -157,7 +192,7 @@ The `ask_question` tool lets the model pause and ask the user one question, rath
 - `question`: the question to put to the user, with the context needed to answer it.
 - `options`: two or three mutually exclusive choices, each with a `label` and a one-sentence `description`. Channels render these as buttons or a select menu. Omit `options` for an open-ended question.
 
-The user can always type their own answer instead of picking an option, so the model never needs an "Other" option. The tool returns `{ status: "answered", answer }` with the chosen option's label or the user's words, `{ status: "dismissed" }` when the user moved on without answering, or `{ status: "unavailable" }` when the session cannot request input.
+The user can always type their own answer instead of picking an option, so the model never needs an "Other" option. The tool returns `{ status: "answered", answer }` with the chosen option's label or the user's words, `{ interrupted: true }` when a new message arrived that did not answer the question, or `{ status: "unavailable" }` when the session cannot request input.
 
 `ask_question` is an [opt-in framework tool](/docs/concepts/built-in-tools#ask_question). Add it with `eve add tool/ask_question`, which creates this file:
 
@@ -169,16 +204,18 @@ export default askQuestion();
 
 `ask_question` is an ordinary [workflow tool](/docs/tools/workflows) built on `ctx.ask()`. Write your own workflow tool with `ctx.ask()` when you need a different schema or want to act on the answer in the same call. Without any asking tool, the model asks in its reply text and the user's next message carries the answer.
 
+In a custom workflow tool, an answered `ctx.ask()` returns the authenticated responder's `authenticator`, `principalId`, and `principalType` when that identity is available. It does not include channel attributes. `ctx.session.auth.current` remains the run's auth snapshot; use the response's `responder` to identify who answered.
+
 ## How pause and resume works
 
 Approvals and questions share one protocol:
 
 1. A tool call needs approval, or a workflow tool such as `ask_question` calls `ctx.ask()`.
 2. eve emits an `input.requested` stream event carrying the pending requests.
-3. The turn parks at `session.waiting`, durably, for as long as it takes.
+3. The run parks durably, for as long as it takes. An approval ends the turn with `turn.completed`, then `session.waiting`. A question keeps the turn open: the stream emits `turn.waiting`, and after the answer the turn resumes under the same `turnId`.
 4. The client answers with `inputResponses` (structured, keyed by `requestId`) or a normal follow-up `message`. A follow-up whose text matches an option ID, option label, or numeric option index resolves automatically, including approval options such as `approve` and `cancel`.
 
-For `ctx.ask()` questions from blocking tools, a follow-up message answers the question only when exactly one question is pending. The message must match an option, or the question must allow free text. Otherwise the message reaches the model as a normal turn, and each pending question created with `dismissible: true` resolves as `dismissed`. Questions from background tools and subagents need a structured response.
+For `ctx.ask()` questions from tools, a follow-up message answers the question only when exactly one question is pending. The message must match an option, or the question must allow free text. Otherwise the message follows the session's `turnPolicy`. A steering message, the default, aborts the `ctx.abortSignal` of each `execute` workflow tool call the turn waits on, so a question such a call asked, such as `ask_question`'s, is withdrawn and resolves as `cancelled`. The model reads the message once those calls settle. Questions from subagents need a structured response.
 
 Each request includes a `kind` discriminator: `tool-approval`, `question`, or
 `session-limit`. Clients should use `kind` to choose behavior and presentation.
@@ -187,7 +224,7 @@ tool call that raised it; neither encodes the request's 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.
+When a 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 records that pending state in model-visible session history. Follow-up turns run normally and may call other tools while the approval remains unresolved. Once it is answered, eve settles the original tool call exactly once.
 

package/docs/tools/meta.json

@@ -1,5 +1,5 @@
 {
   "title": "Tools",
   "defaultOpen": false,
-  "pages": ["overview", "human-in-the-loop", "workflows"]
+  "pages": ["overview", "human-in-the-loop", "workflows", "tasks", "tasks-upgrade"]
 }

package/docs/tools/overview.mdx

@@ -60,6 +60,52 @@ The option defaults to `true` and works with `defineTool` and `defineWorkflowToo
 
 Compiled tools preserve Zod schema composition, including input and output schemas imported from helper modules. Durable replay metadata stays separate from the original schema, so adding it does not mutate shared schema objects.
 
+### End the turn after a tool call
+
+Set `endsTurn: true` when a successful call is the whole answer, such as reacting to a message. eve ends the turn after the call instead of calling the model again, so the turn completes without a final message and channels post no reply:
+
+```ts title="agent/tools/react.ts"
+export default defineTool({
+  description: "React to the current message. Use this when a reaction is the whole answer.",
+  endsTurn: true,
+  inputSchema: z.object({ emoji: z.string() }),
+  async execute({ emoji }) {
+    await addReaction(emoji);
+    return { emoji };
+  },
+});
+```
+
+With `endsTurn: true`, eve tells the model that the call ends its turn by appending this sentence, after a blank line, to the description the model sees:
+
+```text
+Calling this tool ends your turn once it succeeds: do not write a reply or call other tools in the same step. If it fails, you will see the error and can continue.
+```
+
+Write `description` for what the tool does and when to use it, and leave the turn-ending rule to eve. The appended sentence is not part of the tool definition, so `eve info` shows the description as you wrote it.
+
+To decide from the result instead, pass a function. eve calls it with the output of `execute` after each successful call, and the call ends the turn only when the function returns `true` or resolves to `true`. If the function throws or rejects, eve logs a warning and the turn continues as though it returned `false`:
+
+```ts title="agent/tools/react.ts"
+export default defineTool({
+  description:
+    "React to the current message. When the reaction posts, your turn ends; otherwise, reply in text.",
+  inputSchema: z.object({ emoji: z.string() }),
+  async execute({ emoji }) {
+    return { posted: await addReaction(emoji) };
+  },
+  endsTurn: (output) => output.posted,
+});
+```
+
+Declare `endsTurn` after `execute`, as above, so TypeScript infers `output` from what `execute` returns. With an `outputSchema`, `output` takes that schema's type wherever `endsTurn` appears.
+
+eve does not append the sentence for a function, because whether the call ends the turn is known only after it runs. Describe the behavior in `description` when the model needs to know it.
+
+The turn ends only when every tool call in the model's step can end the turn and succeeds, and every `endsTurn` function returns `true`. Otherwise the model receives the results and continues as usual. Text the model writes before the call is narration, so channels do not post it as the reply. While [tasks](/docs/tools/tasks) are still working, the turn waits for them and then calls the model again.
+
+eve ignores `endsTurn` in delegated sessions, which must return a reply to their caller, and on turns that request structured output; the model does not see the appended sentence there, and eve does not call an `endsTurn` function. `defineWorkflowTool` rejects `endsTurn` at build time. Dynamic tool entries accept `endsTurn: true` or `false`; eve rejects a function when the resolver returns the entry, because dynamic tool metadata is stored durably. To end a turn without taking any other action, add the opt-in [`no_reply`](/docs/concepts/built-in-tools#no_reply) tool.
+
 ### Label tool activity
 
 Use `label.start(input)` to describe a call in user-facing activity. The callback receives the validated tool input, so it can select the useful fields without exposing the full argument object:
@@ -86,7 +132,7 @@ Provided tools define labels for `bash`, `glob`, `grep`, `load_skill`, `read_fil
 
 ### Stream preliminary tool results
 
-For a `defineTool` executor with the default execution mode, an async generator streams complete
+For a `defineTool` executor, an async generator streams complete
 output snapshots before it finishes. Each `yield` replaces the previous snapshot; the final
 yield is the normal tool result the model receives:
 
@@ -112,8 +158,8 @@ snapshot is visible to channels, hooks, and clients but never enters model
 history or `toModelOutput`; only the final yield does. Treat snapshots as
 last-write-wins by tool call id, not append-only progress. The durable runtime
 can retry a step and replay overlapping snapshots. A generator `return` value is not used as
-the result in this mode; yield the final output. Workflow and background generators have
-different result rules, described under [yield and return](#yield-and-return).
+the result in this mode; yield the final output. Workflow generators have different result
+rules, described under [yield and return](#yield-and-return).
 
 Use `label.delta(input, partial)` to project preliminary snapshots into
 user-facing activity, and `label.complete(input, output)` to describe successful
@@ -128,69 +174,42 @@ label. `label.complete` does not run for failed or rejected tool calls. The
 full values remain available in `action.partial` and `action.result`; renderers
 receive only the projected text.
 
-### Background execution
-
-Background execution controls how a workflow tool delivers its result to the parent agent.
-Set `execution: "background"` on `defineWorkflowTool`; ordinary `defineTool` calls always finish
-inside the initiating step.
-
-| Definition                                       | Durable waits inside `execute`                           | Result delivered to the model                                                                          |
-| ------------------------------------------------ | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `defineTool`                                     | No; the executor runs inside the initiating step.        | Executor output after it finishes.                                                                     |
-| `defineWorkflowTool`                             | Yes; the tool call waits while the workflow can suspend. | Workflow output after it finishes.                                                                     |
-| `defineWorkflowTool` + `execution: "background"` | Yes; the workflow body can outlive the initiating step.  | Task receipt before the body finishes; one combined report after all tasks in its cohort are terminal. |
-
-A background workflow tool's result is the receipt `{ status: "working", taskId }`; its eventual
-output belongs to the task. Use this mode when the conversation should continue while the body
-waits for a person, webhook, or timer.
-
-For background tools, `outputSchema` and `toModelOutput` describe the fixed receipt. The body's
-return value is available through the completed task's output.
-
-The `TaskExec` argument and `task.postMessage` have been removed. Return the terminal result;
-background yields are consumed without publishing progress or retaining a task-progress stream. In a workflow body, keep values needed after a wait in local variables; workflow replay
-reconstructs them across durable waits.
-Use [`ctx.ask`](/docs/tools/workflows#ask-a-human-ctxask) when the body needs an answer from the human.
-Background tools are a normal execution mode and need no root-agent flag. Built-in, declared local,
-and remote subagents use this task lifecycle automatically.
-
-After the initiating turn accepts background tasks, eve supplies runtime-authored state for that
-cohort and instructs the model to acknowledge that the work started without waiting for results.
-[Schedule](/docs/schedules)-initiated turns are the exception: no user prompted them, so their
-launches keep conditional delivery and send no acknowledgement.
-Channel sessions default to `taskDeliveryPolicy: "auto"`: ready results can invoke
-the parent while other tasks continue. The parent reports independently useful
-results and can stay silent until related work settles. Each reporting context
-includes the whole cohort and available outputs, including previously withheld
-results. Ready results may share a turn.
-Schedules default to `"cohort"`: terminal outcomes wait for overlapping tasks
-to settle, then arrive together. Pass `taskDeliveryPolicy` to `send(...)` to select
-or update the session policy. See
-[Background task results](/docs/channels/overview#background-task-results) and
-[Schedules](/docs/schedules#background-task-results).
-User questions, input requests, and explicit task messages do not wait for the
-cohort under either policy. Failure and cancellation update lifecycle state
-immediately; their automatic reports follow the selected policy.
-See [Completion batching](/docs/subagents#completion-batching).
+### Durable waits
+
+Every tool call finishes before its turn continues. The definition decides whether the executor
+can wait durably while the call is pending:
+
+| Definition           | Durable waits inside `execute`                           | Result delivered to the model      |
+| -------------------- | -------------------------------------------------------- | ---------------------------------- |
+| `defineTool`         | No; the executor runs inside the initiating step.        | Executor output after it finishes. |
+| `defineWorkflowTool` | Yes; the tool call waits while the workflow can suspend. | Workflow output after it finishes. |
+
+A workflow tool that defines `task(input, ctx)` in place of `execute` runs each call as a
+[task](/docs/tools/workflows#run-calls-as-tasks-task):
+the call returns a receipt at once, and the workflow's output reaches the model later in a
+`task.result` message. One that defines `serve(receive, ctx)` runs a
+[resumable task](/docs/tools/workflows#resumable-tasks-serve), which the model can send more calls
+by its `taskId`.
+
+The `TaskExec` argument and `task.postMessage` have been removed. Return the result. In a workflow
+body, keep values needed after a wait in local variables; workflow replay reconstructs them across
+durable waits. Use [`ctx.ask`](/docs/tools/workflows#ask-a-human-ctxask) when the body needs an
+answer from the human. Built-in, declared local, and remote subagent calls also block: each call
+returns the child's reply as its tool result.
 
 ### Yield and return
 
 `yield` hands a value to eve's generator consumer, which processes it and advances the generator.
 It does not by itself create a durable wait for a person, timer, or external event. The value's
-meaning depends on the tool's execution mode:
-
-| Executor                                            | Ordinary `yield value`                                                                  | Final output                                                                                                      |
-| --------------------------------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `defineTool`, default execution                     | Earlier values are `action.partial` snapshots; the final yield becomes the tool result. | Last yielded value; a generator `return` value is ignored.                                                        |
-| `defineWorkflowTool`, default execution             | Every yield is an `action.partial` snapshot.                                            | Explicit return value; falls back to the last yield if the return is `null` or `undefined`, then to `null`.       |
-| `defineWorkflowTool` with `execution: "background"` | Consumed without publishing progress or requesting a parent-agent turn.                 | Explicit return value becomes the task output; no return completes with `null`. The last yield is not a fallback. |
+meaning depends on the executor:
 
-For a background workflow tool, return completes the task and throw fails it. The automatic
-cohort report is separate from the original tool call's receipt.
+| Executor             | Ordinary `yield value`                                                                  | Final output                                                                                                |
+| -------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `defineTool`         | Earlier values are `action.partial` snapshots; the final yield becomes the tool result. | Last yielded value; a generator `return` value is ignored.                                                  |
+| `defineWorkflowTool` | Every yield is an `action.partial` snapshot.                                            | Explicit return value; falls back to the last yield if the return is `null` or `undefined`, then to `null`. |
 
-Progress snapshots do not enter model history as intermediate tool results. For a default
-executor, the final output selected by the rules above becomes the tool result. For a background
-executor, the terminal cohort report provides input to a later parent-agent turn.
+Progress snapshots do not enter model history as intermediate tool results. The final output
+selected by the rules above becomes the tool result.
 
 ### Workflows as tools
 
@@ -206,6 +225,7 @@ examples.
 - `ctx.session`: session metadata, turn, auth, parent lineage.
 - `ctx.callId`: the id of the current tool call, carried by the call's [stream events](/docs/concepts/sessions-runs-and-streaming) and approval context.
 - `ctx.toolName`: the final runtime name the model called, including any namespace qualification.
+- `ctx.messages`: the model input for the step that requested this call, the same messages a `step.started` [dynamic resolver](/docs/guides/dynamic-capabilities) reads.
 - `ctx.abortSignal`: aborts when the active turn is cancelled. Pass it to cancellation-aware work; sandbox sessions from `ctx.getSandbox()` are already bound to it.
 - `ctx.getSandbox()`: the live [sandbox](/docs/sandbox) handle.