eve 0.67.2 → 0.69.0

package/docs/tools/tasks-upgrade.md

@@ -0,0 +1,201 @@
+---
+title: "Upgrade to Tasks"
+description: "Move workflow tools, agent calls, clients, hooks, and evals from background tasks to tasks."
+url: /tools/tasks-upgrade
+---
+
+This release replaces background tasks with [tasks](/docs/tools/tasks). Every change below breaks
+the previous API. Work through the sections that apply to your agent. A workflow tool that uses
+none of `execution: "background"`, `dismissible`, or `ctx.agent` keeps its code: `execute(input,
+ctx)` keeps its signature, and `ctx.abortSignal` and `ctx.callId` are where they were. One behavior
+changes for every `execute` tool: a steering message now aborts its `ctx.abortSignal`. See
+[Drop `dismissible`](#drop-dismissible-a-new-message-stops-an-execute-call).
+Type-checking flags most of the code changes, such as the removed `execution` and `dismissible`
+options and the old `ctx.agent` call.
+
+## Replace `execution: "background"` with `task(input, ctx)`
+
+Rename `execute` to `task` and remove `execution`. The body doesn't change:
+
+```diff
+ export default defineWorkflowTool({
+   description: "Deploy a service.",
+   inputSchema: z.object({ service: z.string() }),
+-  execution: "background",
+-  async execute({ service }, ctx) {
++  async task({ service }, ctx) {
+     "use workflow";
+     return await deploy(service, ctx.abortSignal);
+   },
+ });
+```
+
+`defineWorkflowTool` rejects `execution` with
+`"execution" was replaced by task(). Define task(input, ctx) to run each call as a task.` A
+`task` body gets the same `WorkflowToolContext` as an `execute` body, and steering never aborts a
+task's `abortSignal`. An `execute` tool is an ordinary tool call: the turn waits for its result. See
+[Choose how a call runs](/docs/tools/tasks#choose-how-a-call-runs).
+
+A tool that the model should be able to send more input while it works, such as a plan it revises
+on request, defines [`serve(receive, ctx)`](/docs/tools/workflows#resumable-tasks-serve) instead.
+
+## Drop `dismissible`: a new message stops an `execute` call
+
+`ctx.ask` no longer accepts `dismissible`. A steering message now aborts the `ctx.abortSignal` of
+each `execute` call the turn waits on, which withdraws every question the call asked, as
+`dismissible: true` did:
+
+```diff
+-const answer = await ctx.ask({ prompt, dismissible: true });
++const answer = await ctx.ask({ prompt });
+```
+
+To keep a question open through new messages, ask it from a
+[`task`](#replace-execution-background-with-taskinput-ctx) instead. Other work that
+receives `ctx.abortSignal`, such as a step or a `ctx.agent` send, stops too. The call settles with
+what the body returns, or with `{ interrupted: true }` if the body rejects, and the model reads the
+message next.
+
+A withdrawn question resolves as `{ status: "cancelled" }` instead of `dismissed`, and the
+`input.resolved` outcome `"dismissed"` is now `"cancelled"`. Update clients and channels that
+match on the old value. See [Pass signals to the work](/docs/tools/tasks#pass-signals-to-the-work).
+
+## Open agent sessions with `ctx.agent(name)`
+
+`ctx.agent(name, { message, agentId })`, which returned the agent's output, is now
+`ctx.agent(name)`, which returns a session. Send a message and read the turn's result:
+
+```diff
+-const review = await ctx.agent("reviewer", { message: plan });
++const response = await ctx.agent("reviewer").send(plan, { signal: ctx.abortSignal });
++const { message: review, status } = await response.result();
++if (status === "failed") throw new Error("The review failed.");
+```
+
+`agentId` is removed. Each `ctx.agent(name)` call returns a new session, and later `send` calls on
+the same handle continue its conversation until the workflow run finishes. See
+[Delegate work](/docs/tools/workflows#delegate-work-ctxagent). The `workflow` tool's generated
+programs keep their `ctx.agent(name, { message, outputSchema? })` capability.
+
+## Continue agents by `taskId`
+
+Every agent tool is now a `serve` tool, so every agent call is a resumable task. The model's agent
+tools take `taskId` instead of `agentId`:
+
+```diff
+-{ "message": "Check the Q2 numbers too.", "agentId": "…" }
++{ "message": "Check the Q2 numbers too.", "taskId": "researcher-7k2m9q" }
+```
+
+An agent call returns a receipt at once, and the agent's reply arrives later in a `task.result`
+message. Update instructions, prompts, and evals that mention `agentId` or expect the reply as
+the tool result. `agentRouter()` and the `workflow` tool now run each call as a task too.
+
+The removed codes `AGENT_BUSY`, `AGENT_MISMATCH`, `AGENT_UNREACHABLE`, and
+`AGENT_INVOCATION_NOT_ADMITTED` have no replacement. A `taskId` that names no unfinished task of
+that tool fails with `UNKNOWN_TASK`, and a call past the limit of 32 working tasks fails with
+`TOO_MANY_TASKS`.
+
+## Remove background delivery options
+
+Results reach the model one way: a `task.result` message at a step boundary. Remove these:
+
+- `taskDeliveryPolicy` and delivery cohorts.
+- The `tasks` option of `session.cancel()`. `session.cancel()` now cancels the turn, the `execute`
+  calls it waits on, and every working task; it still accepts `turnId` and `signal`.
+
+The model no longer sees `[Task state]` or `[Agents]` notes, prose task notifications,
+`<eve-empty-delivery/>`, or result turns. A `[Tasks]` note lists its working and idle tasks
+instead. The `BACKGROUND_TASK_FAILED` and `BACKGROUND_TASK_CANCELLED` codes are removed; a
+failed task reports its error in `task.settled` and in its `task.result` block.
+
+## Read task events instead of `subagent.*` events
+
+The `subagent.called`, `subagent.started`, `subagent.completed`, and `subagent.event` events are
+removed. Use these instead:
+
+| Event           | Replaces             | Data                                                                                             |
+| --------------- | -------------------- | ------------------------------------------------------------------------------------------------ |
+| `task.started`  | `subagent.called`    | `taskId`, `callId`, `turnId`, `name`, `kind`                                                     |
+| `task.settled`  | `subagent.completed` | `taskId`, `callId`, `turnId`, `name`, `kind`, `status`, and `output` or `error` unless cancelled |
+| `agent.started` | `subagent.started`   | `callId`, `turnId`, `taskId`, `name`, `sessionId`, `streamPath`                                  |
+
+Follow a child's own events, which `subagent.event` used to relay, on its stream:
+`session.streamSubagent()` is now `session.agent(started).stream()`, and it takes the `agent.started` event.
+
+```diff
+ for await (const event of session.stream()) {
+-  if (event.type !== "subagent.called") continue;
++  if (event.type !== "agent.started") continue;
+-  for await (const childEvent of session.streamSubagent(event)) {
++  for await (const childEvent of session.agent(event).stream()) {
+```
+
+Hooks subscribe the same way:
+
+```diff
+ export default defineHook({
+   events: {
+-    async "subagent.completed"(event, ctx) {
++    async "task.settled"(event, ctx) {
++      if (event.data.status !== "completed") return;
+```
+
+The eval assertion `t.calledSubagent(name, { status })` keeps its API and reads task events.
+
+## Handle open turns in clients
+
+A turn doesn't end while tasks are working, so one turn can span a wait. The stream
+reports each wait with the new `turn.waiting` event, which carries the open turn's `turnId`:
+
+- **Held turns.** When the model ends its text while its tasks work, and when `task_wait` has no
+  result yet, the stream emits `turn.waiting`. The next `step.started` for the same `turnId` means
+  the turn resumed. In a root session, the text before the wait completes as a normal
+  `message.completed`; in child sessions and a schedule's sessions, that step reports
+  `finishReason: "tool-calls"`.
+- **Questions and sign-ins inside a call no longer end the turn.** Previously, a question or
+  sign-in from inside a running call, such as a workflow tool's `ctx.ask()`, `ask_question`, or a
+  subagent's question, emitted `turn.completed` and `session.waiting` in the middle of the turn.
+  It now emits `input.requested` or `authorization.required`, then `turn.waiting`, and the turn
+  resumes under the same `turnId` after the answer. The session you answer on emits
+  `input.resolved` for every question it routes an answer to. A tool approval the turn itself
+  requests still ends the turn with `turn.completed` and `session.waiting`.
+- **`turn.completed` comes only when the turn really ends,** and `session.waiting` always means
+  the turn has ended.
+
+The TypeScript client's `send(...).result()` reads past `turn.waiting` and returns the final reply
+of a held turn, not the text written before the wait. It stops at `turn.waiting` only while a
+question is pending, and returns `status: "waiting"` with that question; `respond()` then reads the
+same turn to its end. A custom client that ends a response at `turn.completed` or
+`session.waiting` mid-turn, or that shows the first completed message as the reply, should follow
+the same rule. See [Aggregate a turn](/docs/guides/client/streaming#aggregate-a-turn).
+
+Task results aren't stream events. Background task results used to appear as `message.received`
+with `data.kind: "execution.background_task"`; `message.received` no longer has `kind`, and a task
+result reaches only the model. Read each call's outcome from `task.settled` instead.
+
+The message stream version is now 26. The TypeScript client accepts versions 21 through 26. A
+client that accepts only versions up to 25 fails the stream with an unsupported-version error. See
+[Turns wait for their tasks](/docs/tools/tasks#turns-wait-for-their-tasks).
+
+## Upgrade remote agents before their callers
+
+The remote agent protocol is now version 2. Deploy each [remote agent](/docs/guides/remote-agents)
+before the deployments that call it. A remote agent on this release still serves callers on eve 0.66
+through 0.68, which speak protocol 1. It runs their turns, sends each result to their callback, and
+accepts their follow-up and reset requests. It also sends the remote agent's tool approvals and
+sign-in requests to the caller, and accepts the caller's answers, the same way a 0.66–0.68 remote
+agent does. As in 0.66–0.68, this covers agents the caller's model calls, which run as background
+tasks. When the caller's own workflow tool code calls an agent, its approvals and sign-in requests
+stay on the remote agent's channel.
+
+Two things differ from a remote agent on the caller's own release:
+
+- The caller's channel doesn't show the remote agent's live tool activity nested under the call.
+- `ctx.ask()` in the remote agent returns `unavailable`, because protocol-1 callers don't grant the
+  remote agent input. That's unchanged from 0.66–0.68.
+
+Each protocol-1 create logs `serving a remote agent protocol 1 caller` with the caller's origin.
+
+Upgrade a caller after every remote agent it calls. A caller on this release fails a call at start,
+with an error that names both versions, when the remote agent's deployment speaks protocol 1.

package/docs/tools/tasks.md

@@ -0,0 +1,315 @@
+---
+title: "Tasks"
+description: "Run agent and workflow tool calls as tasks that keep working while the conversation continues, and control how the model waits for, corrects, and cancels them."
+url: /tools/tasks
+---
+
+A task is a tool call that returns a receipt right away and keeps working while the conversation
+continues. Every call to an agent is a task, and so is every call to a
+[workflow tool](/docs/tools/workflows) that defines `task(input, ctx)` or `serve(receive, ctx)`.
+A task's result reaches the model later, in a `task.result` message, and a turn can't end while
+tasks are still working.
+
+This page covers when to use a task, how to order work that depends on a result, the signals a
+workflow tool body receives, and what the model and the stream see.
+
+## Choose how a call runs
+
+A workflow tool defines exactly one entry point, and the entry point answers one question: should
+the conversation continue while the call works?
+
+```ts
+defineWorkflowTool({ /* … */ async execute(input, ctx) {} }); // the turn waits until the call settles
+defineWorkflowTool({ /* … */ async task(input, ctx) {} }); // a task: a receipt now, the result later
+defineWorkflowTool({ /* … */ async serve(receive, ctx) {} }); // a task that accepts more calls
+```
+
+Defining none of the three, or more than one, throws when the tool is defined.
+
+| Call                                                                    | Runs as                   | Result                                            | A new message during the call     |
+| ----------------------------------------------------------------------- | ------------------------- | ------------------------------------------------- | --------------------------------- |
+| `execute` workflow tool, including `sleep` and `ask_question`           | Tool call; the turn waits | The tool result                                   | Aborts the call's `abortSignal`   |
+| `task` workflow tool, including `agentRouter()` and the `workflow` tool | Task                      | A receipt, then a `task.result` message           | Nothing                           |
+| `serve` workflow tool, including every agent tool                       | Resumable task            | A receipt, then a `task.result` message per reply | Nothing                           |
+| `task_wait`                                                             | Wait inside the turn      | Which tasks settled                               | Ends the wait                     |
+| Plain and MCP tools                                                     | Inside the model step     | The tool result                                   | Applied at the next step boundary |
+
+Waiting alone doesn't need a task. A question, a `sleep`, or an approval inside an `execute` call
+parks the turn durably and holds no compute, and a new message stops the wait. Use a task when the
+model should keep talking while the work runs, such as a twenty-minute deploy or research the model
+may not need right away, or when a question should stay open through new messages. A long
+`execute` tool holds the conversation until it settles or a new message stops it.
+
+Agents have no choice to make: every agent tool is a `serve` tool, so every agent call is a
+resumable task, because only the model can tell from the conversation whether it needs an agent's
+answer now. The [turn rule](#turns-wait-for-their-tasks) guarantees the answer reaches the model
+before the turn ends.
+
+See [Run calls as tasks](/docs/tools/workflows#run-calls-as-tasks-task) for writing a `task` body
+and [Resumable tasks](/docs/tools/workflows#resumable-tasks-serve) for `serve` bodies,
+`receive()`, and `ctx.reply()`.
+
+## Order work that depends on a result
+
+Because agent calls are tasks, the model decides when to wait for them. An instruction such as
+"publish only after the review approves" holds only as long as the model follows it. When an order
+must always hold, write a workflow tool that runs the first step through
+[`ctx.agent`](/docs/tools/workflows#delegate-work-ctxagent) and then acts, and don't expose the
+side effect as a separate tool:
+
+```ts title="agent/tools/publish_reviewed_notes.ts"
+import { defineWorkflowTool } from "eve/tools";
+import { z } from "zod";
+import { publishNotes } from "../lib/release";
+
+const Review = z.object({ approved: z.boolean(), reason: z.string() });
+
+export default defineWorkflowTool({
+  description: "Have the reviewer check the release notes, then publish them if approved.",
+  inputSchema: z.object({ notes: z.string() }),
+  async execute({ notes }, ctx) {
+    "use workflow";
+    const response = await ctx.agent("reviewer").send(`Review these release notes:\n\n${notes}`, {
+      outputSchema: Review,
+      signal: ctx.abortSignal,
+    });
+    const { data, status } = await response.result();
+    if (status === "failed" || data === undefined) {
+      throw new Error("The review did not finish.");
+    }
+    if (!data.approved) return { published: false, reason: data.reason };
+    return { published: true, url: await publish(notes) };
+  },
+});
+
+async function publish(notes: string) {
+  "use step";
+  return await publishNotes(notes);
+}
+```
+
+The publish step can only run after the review returns. Set `tool: false` on the `reviewer`
+subagent if the model shouldn't call it directly, and define `task` in place of `execute` if the
+conversation should continue while the review runs.
+
+## Pass signals to the work
+
+A workflow tool body receives its signals from its context or, in a `serve` body, from each call
+`receive()` resolves:
+
+- **`abortSignal`** aborts when the call's work should stop: by `task_cancel`, `session.cancel()`,
+  a cancelled or failed turn, or the end of the session, and, for an `execute` call, by a steering
+  message that arrives while the turn waits on it. `execute` and `task` bodies read it as
+  `ctx.abortSignal`. In a `serve` body, each call from `receive()` carries its own `abortSignal`;
+  every call in one stretch of work shares one signal, and the next stretch gets a new one. Pass it
+  to the steps and `ctx.agent` sends that should stop.
+- **`ctx.ask(request)`** withdraws the question when the call's `abortSignal` aborts, and
+  `ctx.ask(request, { signal })` also when `signal` does. In a `serve` body, `ctx.reply()` also
+  withdraws the questions still pending for the calls it settles. The answer resolves as
+  `{ status: "cancelled" }`, and the stream reports `input.resolved` with `outcome: "cancelled"` so
+  channels stop offering the question. A person's answer that reached the session first still wins:
+  the ask resolves as `answered`, so branch on `status`, not on the signal.
+
+A body doesn't need to tell a steering message from a cancel: in both cases, stop and return what
+you have. After a steering message the call settles with what the body returns, or with
+`{ interrupted: true }` if the body rejects, and the model reads the message next. After a cancel,
+eve discards the result. So a question in an `execute` call lapses once the conversation moves on,
+as the provided `ask_question` tool's does, while a question in a task stays open:
+
+```ts
+async execute({ service }, ctx) {
+  "use workflow";
+  const answer = await ctx.ask({
+    prompt: `Deploy ${service} now?`,
+    display: "confirmation",
+    options: DEPLOY_OR_WAIT,
+  });
+  if (answer.status === "cancelled") return { deployed: false, reason: "the conversation moved on" };
+  // …
+}
+```
+
+See [Stop early for a new message](/docs/tools/workflows#stop-early-for-a-new-message) for how the
+provided `sleep` tool races its timer against the signal.
+
+## What the model sees
+
+eve adds `task_wait`, `task_cancel`, and a short system prompt block that explains tasks whenever
+the agent has an agent tool or a `task` or `serve` workflow tool. The block tells the model to call
+`task_wait` when it has nothing to say until a result arrives, and to reply when the person should
+hear from it first, such as a confirmation that work is underway. In a child session or a
+schedule's session, where only the final reply reaches the caller, it tells the model to call
+`task_wait` instead of replying while tasks work.
+
+**Receipts.** A call that starts a task returns a receipt as its tool result. Task ids are the tool
+name and six characters. A resumable task's receipt tells the model how to reach it again, and a
+call that reaches it by `taskId` returns a short receipt of its own:
+
+```text
+Started task deploy-4hd8sa. Its result will arrive in a <task_result> message.
+Started task researcher-7k2m9q. Its result will arrive in a <task_result> message. To send it another message, call researcher again with taskId researcher-7k2m9q.
+Sent to task researcher-7k2m9q. Its reply will arrive in a <task_result> message.
+```
+
+**Results.** Each result arrives once, as a `<task_result>` block in a `task.result` message that
+eve appends at the next step boundary, right after `task_wait` returns, or when a held turn
+resumes. The body is the tool's `toModelOutput` projection of the output, or the error message for
+a failed call. All results in one message share a budget of 50 KB and 2,000 lines, after which the
+text is cut and marked `[truncated]`.
+
+```text
+<task_result id="deploy-4hd8sa" tool="deploy" status="completed">{"url":"https://…"}</task_result>
+```
+
+**`task_wait({ timeoutSeconds? })`** controls when the model replies. The model should call it
+sparingly, only when it deliberately wants to withhold a message from the user while waiting for
+a task result. Tasks keep running and their results reach the model without this call; the model
+can reply now if the user should hear from it.
+
+The call parks the turn until any task has a result, a new message arrives, or `timeoutSeconds`
+pass. `timeoutSeconds` is a whole number of at least 1, in seconds like `sleep`. It returns at once
+when a result is already waiting. Waiting never stops a task. The
+model reads which tasks settled and which are still working, for example:
+
+```text
+deploy-4hd8sa completed; its result follows. 1 task is still working: researcher-7k2m9q.
+```
+
+**`task_cancel({ taskId })`** stops a task's current work and says so. A resumable task's answer
+also tells the model how to give it new work. When the task has no work to stop, because it already
+finished or is an idle resumable task, `task_cancel` says that instead:
+
+```text
+Stopped deploy-4hd8sa; it won't report back.
+Stopped researcher-7k2m9q's current work; it won't report back. To give it new work, call researcher again with taskId researcher-7k2m9q.
+researcher-7k2m9q had no work to stop.
+```
+
+**`[Tasks]` note.** When the session's tasks change, eve adds a note at the next step boundary that
+lists the working tasks and the 10 most recently used idle resumable tasks. The note returns after
+[compaction](/docs/concepts/default-harness#compaction), so the model can always find a task id:
+
+```text
+[Tasks]
+<tasks>
+<task id="deploy-4hd8sa" tool="deploy" status="working"/>
+</tasks>
+<idle>
+<task id="researcher-7k2m9q" tool="researcher"/>
+</idle>
+```
+
+**Errors.** Two error codes are specific to tasks:
+
+| Code             | When                                                                               |
+| ---------------- | ---------------------------------------------------------------------------------- |
+| `UNKNOWN_TASK`   | A call's `taskId` names no unfinished resumable task that the same tool started    |
+| `UNKNOWN_TASK`   | `task_cancel`'s `taskId` names no task; a finished or idle one has no work to stop |
+| `TOO_MANY_TASKS` | A call would start a task, or make an idle one work, while 32 tasks are working    |
+
+A `final_output` call made while tasks are working returns an error that names them.
+
+## Turns wait for their tasks
+
+No turn ends while any task is working. When the model ends a turn early, eve waits as
+`task_wait` does: it parks until one of the tasks settles or the turn's own caller steers it,
+appends the results, and calls the model again in the same turn. No result ever starts a turn on
+its own. An idle resumable task isn't working, so it doesn't hold the turn.
+
+A held turn stays open. Each time it parks, when eve holds it or when `task_wait` has no result
+yet, the stream emits `turn.waiting` with the turn's `turnId`. The next `step.started` for the
+same `turnId` means the turn resumed, and `session.waiting` comes only after the turn ends. The
+model's text before the wait depends on the session:
+
+- **Root sessions:** the text completes as an ordinary message. The person can keep writing, and
+  the turn resumes under the same id.
+- **Child sessions and a schedule's sessions:** the held text step reports
+  `finishReason: "tool-calls"` on `message.completed`, so channels post only the final reply.
+
+A question or sign-in from a task, such as an agent's question, parks the turn the same way: the
+stream emits `input.requested` or `authorization.required`, then `turn.waiting`, and the turn
+continues once the person answers or signs in.
+
+In every session, `turn.completed` comes only when the turn really ends. The TypeScript client's
+`send(...).result()` and the MCP channel's `agent_get` read past `turn.waiting` and report the
+final reply rather than the text written before the wait. `result()` stops at `turn.waiting` only
+while a question is pending, and returns `status: "waiting"` with it; `respond()` then reads the
+same turn to its end. See [Aggregate a turn](/docs/guides/client/streaming#aggregate-a-turn).
+Channels such as [Slack](/docs/channels/slack) post a root session's text before the wait as an
+ordinary reply, then post the reply after the results as another message. Slack also shows each
+turn's tasks in a live [task card](/docs/channels/slack#task-card).
+
+A steering message from the turn's own caller, one sent with `turnPolicy: "steer"`, the default,
+ends a `task_wait` and aborts the `abortSignal` of any `execute` call the turn waits on, but it
+never interrupts a task. The model reads the message and decides whether to keep each task,
+correct an agent by calling it again with its `taskId`, or stop a task with `task_cancel`. A
+`"queue"` message, or a message from another caller, waits for the turn to end.
+
+## Cancel a task
+
+- **`task_cancel`** stops one task's current work.
+- **`session.cancel()`** cancels the turn, the `execute` calls it waits on, and every working task
+  in the session.
+- **A failed turn** cancels every working task.
+- **The end of the session** ends every task.
+
+Cancelled work never reports back. A `task` tool's task is then finished; its run waits up to 30
+seconds for the body to finish unwinding, then ends as cancelled. A `serve` tool's task stays
+available instead: its waiting calls settle as `cancelled`, the stretch's `abortSignal` aborts, and
+the task becomes idle, as long as the body catches that abort and returns to `receive()`. For an
+agent, that cancels the agent's current turn and keeps its conversation, so a later call with the
+same `taskId` continues where it left off. A `serve` body that doesn't return to `receive()` within
+30 seconds of a cancel ends, and the task finishes.
+
+## Stream events
+
+| Event           | When                                                                     | Data                                                                                       |
+| --------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
+| `task.started`  | A call starts a task, or reaches a resumable task by its `taskId`        | `taskId`, `callId`, `turnId`, the tool `name`, and `kind`                                  |
+| `task.settled`  | A reply, return, failure, or cancel settles one call                     | `taskId`, `callId`, `turnId`, `name`, `kind`, `status`, and `output`, `error`, or `cancel` |
+| `agent.started` | A workflow run, including an agent tool's, opens a session with an agent | `callId`, `turnId`, `taskId`, `name`, `sessionId`, `streamPath`                            |
+| `turn.waiting`  | An open turn parks on its tasks, a `task_wait`, a question, or a sign-in | `turnId` and `sequence`                                                                    |
+
+`task.started` and `task.settled` come once each per call, and `(taskId, callId)` identifies the
+call. Both carry that call's `turnId`, which for a resumable task's later call can be a later turn
+than the one that started the task, and the task's tool `name` and `kind`. `kind` is `"agent"` for
+an agent tool's call and `"tool"` otherwise. Events recorded by earlier eve versions omit `name`
+and `kind` on `task.settled`; match those to their `task.started` by `callId`. `status` is `"completed"`, `"failed"`, or `"cancelled"`. A completed call carries
+`output`, a failed call carries `error`, and a cancelled call carries `cancel.reason`:
+`"task_cancel"` when the model called `task_cancel`, `"turn_cancelled"` when someone cancelled
+the turn, or the working tasks between turns, or `"turn_ended"` when the turn ended, such as by
+failing, while the task still worked. `cancel` is absent when the task's run stopped on its own, and on events recorded by
+earlier eve versions.
+`agent.started` names the call and turn whose run opened the session, and its `taskId` is absent
+when an `execute` call opened it. Results reach the model as a message in its history, not as a
+stream event, so read outcomes from `task.settled`. An `input.requested`,
+`authorization.required`, or `authorization.completed` event from a task's run carries its
+`taskId`. Hooks subscribe to the same events. The stream also carries the model's `task_wait` and
+`task_cancel` calls as ordinary `actions.requested` tool calls, so evals can assert on them. The
+`eve dev` terminal UI and Slack typing indicators leave those calls out; the terminal UI shows each
+task's start and end instead. See
+[Sessions, runs, and streaming](/docs/concepts/sessions-runs-and-streaming#task-events) and
+[Follow a subagent](/docs/guides/client/streaming#follow-a-subagent).
+
+## Ownership and limits
+
+- **Ownership.** Tasks belong to the session's open turn, not to the caller that started them. A
+  session has at most one open turn, so `task_wait`, `task_cancel`, task results, and the `[Tasks]`
+  note cover every task in the session. Any later turn can continue an idle resumable task by its
+  `taskId`, and that call runs with its own caller's auth. Only the turn's own caller steers it;
+  anonymous callers share one identity.
+  eve doesn't check which caller started a task: in a session with several people, such as a
+  shared Slack thread, the model working for one person can continue or `task_cancel` a task
+  another person started. A continued `serve` task keeps the state its body built for earlier
+  calls, so [key per-caller data on the principal](/docs/tools/workflows#resumable-tasks-serve)
+  and enforce per-person access inside the tool.
+- **Working tasks.** A session runs at most 32 working tasks at once. An idle resumable task doesn't
+  count, and a call that makes it work again does.
+- **No time limits.** Tasks have no timeout of their own. The session lifetime,
+  `limits.sessionTimeoutMs` (30 days by default), bounds all work in a session. A body that needs a
+  deadline races `sleep` against its work.
+
+## Upgrade from background tasks
+
+Tasks replace background tasks, `execution: "background"`, and `agentId` continuation. See
+[Upgrade to Tasks](/docs/tools/tasks-upgrade) for every breaking change.