eve 0.51.1 → 0.52.0

package/docs/reference/cli.md

@@ -1,43 +1,48 @@
 ---
 title: "CLI"
-description: "Reference for every eve CLI command: init, set, info, build, start, dev, logs, trace, link, deploy, eval, channels, and extension."
+description: "Reference for every eve CLI command: init, set, info, build, start, dev, logs, traces, link, deploy, eval, channels, extension, and telemetry."
 ---
 
-Relevant `eve` commands can run from the application root or any directory beneath it. In an `agents/` workspace, agent-specific commands accept `--agent <name>` and otherwise open a picker when more than one agent exists. Non-interactive runs must pass `--agent`. Running `eve` with no command runs `eve init` when the current directory is not an eve project, or `eve dev` when it is.
+Relevant `eve` commands can run from the application root or any directory beneath it. Running `eve` with no command runs `eve init` when the current directory is not an eve project, or `eve dev` when it is.
 
 ## Commands
 
-| Command                        | Description                                                                                                                        |
-| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
-| `eve`                          | Initialize the current directory, or start development when it is already an eve project                                           |
-| `eve init [target]`            | Create a new agent, or add an agent to an existing project                                                                         |
-| `eve info`                     | Print the resolved application, including static instructions and discovered capabilities, routes, artifact paths, and diagnostics |
-| `eve build`                    | Compile `.eve/` artifacts and build the host output; prints the output directory                                                   |
-| `eve start`                    | Serve the built `.output/` app; prints the listening URL                                                                           |
-| `eve dev`                      | Start the local dev server and open the terminal UI                                                                                |
-| `eve dev <url>`                | Connect the UI to an existing server URL (e.g. a remote deployment) instead of booting a local server                              |
-| `eve acp [url]`                | Serve the local application or an existing eve server URL as a stable ACP v1 agent over stdio                                      |
-| `eve logs [logid]`             | Print an `eve dev` diagnostic log (the most recent when `logid` is omitted)                                                        |
-| `eve logs ls`                  | List `eve dev` diagnostic logs, most recent first                                                                                  |
-| `eve traces ls`                | List locally captured agent traces, most recent first                                                                              |
-| `eve traces [trace]`           | Show a local span tree (the most recent when omitted)                                                                              |
-| `eve link`                     | Link the directory to a Vercel project and pull AI Gateway credentials                                                             |
-| `eve deploy`                   | Deploy the agent to Vercel production (links first if needed)                                                                      |
-| `eve eval`                     | Run evals against the local app or a remote target                                                                                 |
-| `eve channels list`            | List user-authored channels                                                                                                        |
-| `eve extension init [target]`  | Create a new extension package                                                                                                     |
-| `eve extension build`          | Build the current package as an extension                                                                                          |
-| `eve set`                      | Change the root agent's model and reasoning effort                                                                                 |
-| `eve add <item>`               | Install an item from the official or a configured shadcn registry                                                                  |
+| Command                       | Description                                                                                                                        |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `eve`                         | Initialize the current directory, or start development when it is already an eve project                                           |
+| `eve init [target]`           | Create a new agent, or add an agent to an existing project                                                                         |
+| `eve info`                    | Print the resolved application, including static instructions and discovered capabilities, routes, artifact paths, and diagnostics |
+| `eve build`                   | Compile `.eve/` artifacts and build the host output; prints the output directory                                                   |
+| `eve start`                   | Serve the built `.output/` app; prints the listening URL                                                                           |
+| `eve dev`                     | Start the local dev server and open the terminal UI                                                                                |
+| `eve dev <url>`               | Connect the UI to an existing server URL (e.g. a remote deployment) instead of booting a local server                              |
+| `eve acp [url]`               | Serve the local application or an existing eve server URL as a stable ACP v1 agent over stdio                                      |
+| `eve logs [logid]`            | Print an `eve dev` diagnostic log (the most recent when `logid` is omitted)                                                        |
+| `eve logs ls`                 | List `eve dev` diagnostic logs, most recent first                                                                                  |
+| `eve traces ls`               | List locally captured agent traces, most recent first                                                                              |
+| `eve traces [trace]`          | Show a local span tree (the most recent when omitted)                                                                              |
+| `eve telemetry <command>`     | Show, enable, or disable CLI telemetry collection                                                                                  |
+| `eve link`                    | Link the directory to a Vercel project and pull AI Gateway credentials                                                             |
+| `eve deploy`                  | Deploy the agent to Vercel production (links first if needed)                                                                      |
+| `eve eval`                    | Run evals against the local app or a remote target                                                                                 |
+| `eve channels list`           | List user-authored channels                                                                                                        |
+| `eve extension init [target]` | Create a new extension package                                                                                                     |
+| `eve extension build`         | Build the current package as an extension                                                                                          |
+| `eve set`                     | Change the root agent's model and reasoning effort                                                                                 |
+| `eve add <item>`              | Install an item from the official or a configured shadcn registry                                                                  |
 | `eve integration setup <kind>` | Run a built-in setup flow directly after its registry files are installed                                                          |
-| `eve registry <command>`       | Add sources and list, search, or view registry catalog items                                                                       |
+| `eve registry <command>`      | Add sources and list, search, or view registry catalog items                                                                       |
 
 When `eve build` fails on discovery errors, it prints the full diagnostics report (severity, message, source path) and the diagnostics artifact path.
 
+## CLI telemetry
+
+eve collects CLI telemetry by default to improve the command-line interface. Run `eve telemetry disable` to disable it for this machine, or set `EVE_TELEMETRY_DISABLED=1` for one command. See [CLI telemetry](./telemetry) for the current data fields, exclusions, debug mode, notice, and local preference storage.
+
 ## `eve init`
 
 ```bash
-eve init [target] [--agents <name,...>] [--model <provider/model-id>] [--reasoning <effort>] [--channel-web-nextjs]
+eve init [target] [--model <provider/model-id>] [--reasoning <effort>] [--channel-web-nextjs]
 ```
 
 Creates a new agent app or adds an agent to an existing app. Always installs dependencies. New directories also initialize Git.
@@ -48,8 +53,6 @@ Creates a new agent app or adds an agent to an existing app. Always installs dep
 | `eve init` or `eve init .` in an empty directory                           | Creates an agent project in the current directory                                                                                                                        |
 | `eve init` or `eve init .` in a non-empty directory without `package.json` | Asks whether to scaffold in the current directory or a named subdirectory. Using the current directory preserves unrelated files but overwrites files at generated paths |
 | `eve init .` in an existing project                                        | Adds `agent/` plus missing `eve`, `ai`, and `zod` dependencies. Requires `package.json` and no existing `agent/` files                                                   |
-| `eve init my-project --agents foreman,researcher`                          | Creates a workspace with `agents/foreman/agent/` and `agents/researcher/agent/`                                                                                          |
-| `eve init billing` from an `agents/` workspace                             | Adds only `agents/billing/agent/`; the workspace keeps its existing package, dependencies, and TypeScript configuration                                                  |
 
 Coding-agent launches and non-interactive terminals cannot answer the location prompt and fail before writing. Pass a new directory name, such as `eve init my-agent`, in those environments.
 
@@ -57,7 +60,6 @@ After scaffolding, a human terminal usually continues into `eve dev`. If a codin
 
 | Flag                   | Type   | Default                    | Description                                                                                                              |
 | ---------------------- | ------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `--agents <names>`     | list   | unset                      | Create an `agents/` workspace with one or more comma-separated agent names.                                              |
 | `--model <model>`      | string | `openai/gpt-5.6-luna-fast` | Set the root agent's AI Gateway model ID.                                                                                |
 | `--reasoning <effort>` | enum   | provider default           | Set reasoning to `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. `provider-default` leaves the field unauthored. |
 | `--channel-web-nextjs` | flag   | off                        | Add the Web Chat app (Next.js). Not for existing projects — run `eve add channel/web` there instead.                     |
@@ -122,8 +124,6 @@ Commands for installing and discovering [shadcn registry](https://ui.shadcn.com/
 eve add extension/agent-browser
 eve add linear
 eve add channel/slack --skip-install
-eve add memory/file
-eve integration setup file-memory
 eve add https://example.com/r/my-extension.json --overwrite
 eve registry add @acme=https://example.com/r/{name}.json
 eve registry search browser
@@ -139,8 +139,6 @@ Coding agents should use `eve add <item> --non-interactive`, adding `--yes` to a
 
 When setup is skipped, cancelled, or needs more input after installation, eve prints or returns the matching `eve add <item> --skip-install` continuation. It reruns the selected components' declared flows without reinstalling registry files.
 
-`eve integration setup file-memory` runs the storage setup directly without reinstalling `agent/memory/file.ts`. It authenticates through the Vercel CLI, resolves the linked project, reconciles the private Blob store, and pulls the environment. Use it to repair or verify a previous provisioning attempt; `eve add memory/file` also offers the normal deployment handoff after setup.
-
 `eve registry add` records configured sources in `package.json#registries`. `eve registry list` aggregates the official catalog and all configured sources by default. `eve registry search` also includes [skills.sh](https://skills.sh), available without configuration at `@skills`, and groups results by source with each source's available result count. Search returns up to 10 matches per source by default; pass `--limit <count>` to request between 1 and 100. Either command can browse one supplied URL or namespace. Official and other universal items with explicit file targets do not require shadcn project configuration.
 
 ## `eve info`

package/docs/reference/meta.json

@@ -1,4 +1 @@
-{
-  "title": "Reference",
-  "pages": ["typescript-api", "cli"]
-}
+{ "title": "Reference", "pages": ["typescript-api", "cli", "telemetry"] }

package/docs/reference/telemetry.md

@@ -0,0 +1,56 @@
+---
+title: "CLI Telemetry"
+description: "Learn what eve CLI telemetry collects and how to control it."
+---
+
+# CLI telemetry
+
+eve collects usage data from its CLI to help improve its commands and development experience. You can turn telemetry off at any time.
+
+## What eve collects
+
+eve sends the following information to Vercel:
+
+- The eve version, operating system, CPU architecture, and whether stdin is a terminal.
+- The command you ran and whether it succeeded, had a usage error, or failed.
+- For `eve dev`, whether you connected to a local or remote agent and whether the UI was interactive or headless.
+- Random identifiers for the CLI session, your eve installation, and the project.
+
+The project identifier lets eve group usage from the same project without sending its name or location. eve derives it from the Git remote when available, otherwise `REPOSITORY_URL` or the working directory, and transforms that value before sending it.
+
+## What eve does not collect
+
+eve does not collect command arguments, prompts, agent files, URLs, request headers, error messages, environment variables, file paths, or file contents.
+
+## View telemetry data
+
+Set `EVE_TELEMETRY_DEBUG=1` to print the telemetry batch to stderr instead of sending it:
+
+```bash
+EVE_TELEMETRY_DEBUG=1 eve info
+```
+
+## Turn telemetry off
+
+Disable telemetry for this machine:
+
+```bash
+eve telemetry disable
+```
+
+Check its status or turn it back on:
+
+```bash
+eve telemetry status
+eve telemetry enable
+```
+
+To disable telemetry for one command without changing the saved setting, set `EVE_TELEMETRY_DISABLED=1`:
+
+```bash
+EVE_TELEMETRY_DISABLED=1 eve dev
+```
+
+On an interactive terminal, eve displays this information once before it collects telemetry. eve saves your preference in your platform user configuration directory. In CI and Docker environments, eve uses fresh in-memory identifiers for each invocation instead of saving them.
+
+Vercel handles CLI telemetry under the [Vercel Privacy Notice](https://vercel.com/legal/privacy-notice).

package/docs/reference/typescript-api.md

@@ -34,6 +34,7 @@ export default defineTool({
 | ----------------------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------ |
 | `defineAgent`                                         | `eve`                                                                   | `agent/agent.ts`                                                                       | [agent.ts](../agent-config)                            |
 | `defineTool`                                          | `eve/tools`                                                             | `agent/tools/<name>.ts`                                                                | [Tools](../tools)                                      |
+| `defineWorkflowTool`                                  | `eve/tools`                                                             | `agent/tools/<name>.ts`                                                                | [Workflow tools](../tools/workflows)                   |
 | `defineDynamic`                                       | `eve`, `eve/tools`, `eve/skills`, `eve/instructions`, `eve/connections` | dynamic model or subagent `agent.ts`; `agent/{tools,skills,instructions,connections}/` | [Dynamic capabilities](../guides/dynamic-capabilities) |
 | `defineMcpClientConnection`                           | `eve/connections`                                                       | `agent/connections/<name>.ts`                                                          | [MCP connections](../connections/mcp)                  |
 | `defineOpenAPIConnection`                             | `eve/connections`                                                       | `agent/connections/<name>.ts`                                                          | [OpenAPI connections](../connections/openapi)          |
@@ -53,7 +54,7 @@ export default defineTool({
 | `mockModel`                                           | `eve/evals`                                                             | Deterministic fixture agent models                                                     | [Evals](../evals/overview)                             |
 | `useEveAgent`                                         | `eve/react`, `eve/vue`, `eve/svelte`                                    | frontend                                                                               | [Frontend](../guides/frontend/overview)                |
 
-Tool-wide authoring helpers such as `defineTool`, `defineDynamic`, and `disableTool` come from `eve/tools`. Capability-specific definitions and helpers use their own subpaths (see [Built-in tools](../concepts/built-in-tools)): reusable definitions such as `bash` and `glob` come from `eve/tools/<name>`, `webSearch` comes from `eve/tools/web_search`, `experimental_workflow` comes from `eve/tools/workflow`, `sleep` comes from `eve/tools/sleep`, and approval policies and types come from `eve/tools/approval`. The route verbs `GET`/`HEAD`/`POST`/`PUT`/`PATCH`/`DELETE`/`OPTIONS`/`WS` plus `disableRoute` come from `eve/channels`, and the channel auth helpers `localDev`/`vercelOidc`/`placeholderAuth` come from `eve/channels/auth`.
+Tool-wide authoring helpers such as `defineTool`, `defineWorkflowTool`, `defineDynamic`, and `disableTool` come from `eve/tools`. Capability-specific definitions and helpers use their own subpaths (see [Built-in tools](../concepts/built-in-tools)): reusable definitions such as `bash` and `glob` come from `eve/tools/<name>`, `webSearch` comes from `eve/tools/web_search`, `experimental_workflow` comes from `eve/tools/workflow`, `sleep` comes from `eve/tools/sleep`, and approval policies and types come from `eve/tools/approval`. The route verbs `GET`/`HEAD`/`POST`/`PUT`/`PATCH`/`DELETE`/`OPTIONS`/`WS` plus `disableRoute` come from `eve/channels`, and the channel auth helpers `localDev`/`vercelOidc`/`placeholderAuth` come from `eve/channels/auth`.
 
 `AgentReasoningDefinition` is exported from `eve` for the top-level `defineAgent({ reasoning })` setting. `AgentLimitsDefinition` is exported for `defineAgent({ limits })`. `AgentWorkflowDefinition` and `AgentWorkflowWorldDefinition` are exported from `eve` for the `defineAgent({ experimental: { workflow } })` config shape. `ExperimentalWorkflowToolInput` is exported from `eve/tools/workflow`; `WebSearchToolInput` and `WebSearchProvider` are exported from `eve/tools/web_search`.
 
@@ -107,40 +108,40 @@ import template from "../../prompts/template.txt?raw";
 
 ## Imports at a glance
 
-| Import                                                                      | Holds                                                                     |
-| --------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
-| `eve`                                                                       | `defineAgent`, `defineRemoteAgent`, `defineDynamic`, agent config types   |
-| `eve/tools`                                                                 | `defineTool`, `defineDynamic`, `disableTool`, generic tool types          |
-| `eve/tools/{bash,read_file,write_file,todo,web_fetch,load_skill,glob,grep}` | Individual reusable tool definitions                                      |
-| `eve/tools/approval`                                                        | Approval types and `always`, `once`, `never`                              |
-| `eve/tools/web_search`                                                      | Provider-managed `webSearch` configuration                                |
-| `eve/tools/workflow`                                                        | Experimental `Workflow` tool definition                                   |
-| `eve/tools/sleep`                                                           | Opt-in durable `sleep` tool                                               |
-| `eve/connections`                                                           | `defineMcpClientConnection`, `defineOpenAPIConnection`, `defineDynamic`   |
-| `eve/channels`                                                              | `defineChannel`, `disableRoute`, route verbs                              |
-| `eve/channels/eve`                                                          | `eveChannel`                                                              |
-| `eve/channels/auth`                                                         | `localDev`, `vercelOidc`, `placeholderAuth`                               |
-| `eve/channels/{slack,discord,teams,telegram,twilio,github}`                 | platform channel factories                                                |
-| `eve/hooks`                                                                 | `defineHook`                                                              |
-| `eve/schedules`                                                             | `defineSchedule`                                                          |
-| `eve/skills`                                                                | `defineSkill`, `defineDynamic`                                            |
-| `eve/instructions`                                                          | `defineInstructions`, `defineDynamic`                                     |
-| `eve/memory`                                                                | `defineMemory`, `defineMemoryProvider`, provider and lifecycle types      |
-| `eve/memory/scope`                                                          | `byPrincipal` and memory scope helpers                                    |
-| `eve/memory/file`                                                           | `fileMemory`, `inMemory`, and the conditional document backend contract   |
-| `eve/memory/file/vercel`                                                    | `vercelBlob` and Vercel Blob backend options                              |
-| `eve/context`                                                               | `defineState`, session and state types                                    |
-| `eve/sandbox`                                                               | `defineSandbox`, backends                                                 |
-| `eve/instrumentation`                                                       | `defineInstrumentation`, `isChannel`                                      |
-| `eve/local-dev`                                                             | `getLocalDevCapability`, `LocalDevCapability`                             |
-| `eve/models/openai`                                                         | `chatgpt`, deprecated `experimental_chatgpt`                              |
-| `eve/evals`                                                                 | `defineEval`, `defineEvalConfig`, `mockModel`, eval types                 |
-| `eve/evals/expect`                                                          | `includes`, `equals`, `matches`, `similarity`                             |
-| `eve/evals/reporters`                                                       | `Braintrust`, `JUnit`, `EvalReporter`                                     |
-| `eve/evals/loaders`                                                         | `loadJson`, `loadYaml`                                                    |
-| `eve/react`, `eve/vue`, `eve/svelte`                                        | `useEveAgent`                                                             |
-| `eve/next`, `eve/nuxt`, `eve/sveltekit`                                     | framework bundler plugins                                                 |
-| [`eve/client`](../guides/client/overview)                                   | `Client`, `ClientSession`, health and agent-info schemas, response errors |
+| Import                                                                      | Holds                                                                                  |
+| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `eve`                                                                       | `defineAgent`, `defineRemoteAgent`, `defineDynamic`, agent config types                |
+| `eve/tools`                                                                 | `defineTool`, `defineWorkflowTool`, `defineDynamic`, `disableTool`, generic tool types |
+| `eve/tools/{bash,read_file,write_file,todo,web_fetch,load_skill,glob,grep}` | Individual reusable tool definitions                                                   |
+| `eve/tools/approval`                                                        | Approval types and `always`, `once`, `never`                                           |
+| `eve/tools/web_search`                                                      | Provider-managed `webSearch` configuration                                             |
+| `eve/tools/workflow`                                                        | Experimental `Workflow` tool definition                                                |
+| `eve/tools/sleep`                                                           | Opt-in durable `sleep` tool                                                            |
+| `eve/connections`                                                           | `defineMcpClientConnection`, `defineOpenAPIConnection`, `defineDynamic`                |
+| `eve/channels`                                                              | `defineChannel`, `disableRoute`, route verbs                                           |
+| `eve/channels/eve`                                                          | `eveChannel`                                                                           |
+| `eve/channels/auth`                                                         | `localDev`, `vercelOidc`, `placeholderAuth`                                            |
+| `eve/channels/{slack,discord,teams,telegram,twilio,github}`                 | platform channel factories                                                             |
+| `eve/hooks`                                                                 | `defineHook`                                                                           |
+| `eve/schedules`                                                             | `defineSchedule`                                                                       |
+| `eve/skills`                                                                | `defineSkill`, `defineDynamic`                                                         |
+| `eve/instructions`                                                          | `defineInstructions`, `defineDynamic`                                                  |
+| `eve/memory`                                                                | `defineMemory`, `defineMemoryProvider`, provider and lifecycle types                   |
+| `eve/memory/scope`                                                          | `byPrincipal` and memory scope helpers                                                 |
+| `eve/memory/file`                                                           | `fileMemory`, `inMemory`, and the conditional document backend contract                |
+| `eve/memory/file/vercel`                                                    | `vercelBlob` and Vercel Blob backend options                                           |
+| `eve/context`                                                               | `defineState`, session and state types                                                 |
+| `eve/sandbox`                                                               | `defineSandbox`, backends                                                              |
+| `eve/instrumentation`                                                       | `defineInstrumentation`, `isChannel`                                                   |
+| `eve/local-dev`                                                             | `getLocalDevCapability`, `LocalDevCapability`                                          |
+| `eve/models/openai`                                                         | `chatgpt`, deprecated `experimental_chatgpt`                                           |
+| `eve/evals`                                                                 | `defineEval`, `defineEvalConfig`, `mockModel`, eval types                              |
+| `eve/evals/expect`                                                          | `includes`, `equals`, `matches`, `similarity`                                          |
+| `eve/evals/reporters`                                                       | `Braintrust`, `JUnit`, `EvalReporter`                                                  |
+| `eve/evals/loaders`                                                         | `loadJson`, `loadYaml`                                                                 |
+| `eve/react`, `eve/vue`, `eve/svelte`                                        | `useEveAgent`                                                                          |
+| `eve/next`, `eve/nuxt`, `eve/sveltekit`                                     | framework bundler plugins                                                              |
+| [`eve/client`](../guides/client/overview)                                   | `Client`, `ClientSession`, health and agent-info schemas, response errors              |
 
 Exported types ship from the same entrypoint as the helper they describe (for example `ToolDefinition` and `ToolContext` from `eve/tools`). The `exports` field in `packages/eve/package.json` lists every public entrypoint.
 
@@ -182,6 +183,8 @@ export default defineAgent({
 
 Pass another bare OpenAI model slug to override the default. `experimental_chatgpt()` remains as a deprecated alias.
 
+`chatgpt()` uses stateless requests (`store: false`). eve retains reasoning summaries and encrypted reasoning in session history and replays them after tool calls and on later turns. You do not need to configure `reasoning.encrypted_content` explicitly.
+
 Authentication is delegated entirely to the Codex CLI:
 
 1. Install or upgrade `codex` and run `codex login`.

package/docs/tools/overview.mdx

@@ -34,8 +34,8 @@ When a tool returns structured data, add an optional `outputSchema`. With Zod or
 
 ### Stream preliminary tool results
 
-An async generator lets a long-running tool stream complete output snapshots
-before it finishes. Each `yield` replaces the previous snapshot; the final
+For a `defineTool` executor with the default execution mode, 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:
 
 ```ts title="agent/tools/build_report.ts"
@@ -54,22 +54,43 @@ eve publishes every earlier yield as an `action.partial` stream event. The
 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.
+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).
 
 ### Background execution
 
-`defineTool({ execution: "background" })` receives a third `task` argument. Returning a normal
-value completes the durable task with that value. Returning `task.delegated({ executor, receipt })`
-returns a `working` receipt immediately while an external executor continues the task. Background
-tools are a normal execution mode and need no root-agent flag.
-
-Built-in, declared local, and remote subagents use this background task lifecycle automatically.
-After delegating, an
-in-process executor reports
-progress with `task.send({ kind: "update", message })` and the terminal result with
-`task.send({ kind: "complete", data })` (or `fail` / `cancel`). `send` is not restart-safe — an
-in-memory callback dies with the process — so the cross-process executor wire remains
-framework-owned and is not yet a stable authored-tool API.
+Background execution controls how a tool delivers its result to the parent agent. Durable
+suspension controls whether the executor can pause at a workflow wait and release compute.
+These are independent choices: `execution: "background"` selects the task lifecycle;
+`defineWorkflowTool` with a leading `"use workflow"` directive enables durable suspension.
+
+| Definition                                       | Durable waits inside `execute`                                  | Result delivered to the model                                          |
+| ------------------------------------------------ | --------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `defineTool`                                     | No; the executor runs inside the initiating step.               | Executor output after it finishes.                                     |
+| `defineTool` + `execution: "background"`         | No; the initiating step still waits for the executor to finish. | Task receipt, followed by task notifications.                          |
+| `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, followed by task notifications. |
+
+A background tool receives a third `task` argument. Its tool result is the receipt
+`{ status: "working", taskId }`; its eventual output belongs to the task. Use a background
+workflow tool when the conversation should continue while the body waits for a person,
+webhook, or timer. Setting `execution: "background"` on an ordinary tool does not move its
+executor into a separate workflow or make an ordinary Promise a durable wait.
+
+For background tools, `outputSchema` and `toModelOutput` describe the fixed receipt. The body's
+return value is available through the completed task's output.
+
+`task.delegated()` has been removed. Move external work into a `defineWorkflowTool` executor and
+return its result when it finishes. Rebuild extensions using the removed API after migrating.
+
+`yield task.postMessage(message)` is the only yield that requests a parent-agent turn. Calling
+`task.postMessage` only constructs the message descriptor; you must yield it to send it.
+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.
@@ -79,11 +100,31 @@ Later task-triggered parent turns receive fresh state for the same cohort. The m
 to keep related intermediate results silent while any task remains pending. Once every related
 task is terminal, the state includes their outputs so the model can combine the useful results.
 
+### 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`.       |
+| Either definition with `execution: "background"` | Stream-only task progress; does not request a parent-agent turn.                        | Explicit return value becomes the task output; no return completes with `null`. The last yield is not a fallback. |
+
+For either kind of background tool, `yield task.postMessage(message)` sends a message to the
+parent agent while the task remains open. Return completes the task; throw fails it. These
+notifications are separate from the original tool call's receipt.
+
+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, task messages and completion notifications provide input to later parent-agent turns.
+
 ### Workflows as tools
 
-Put `"use workflow"` at the start of a tool's `execute` function to run each call as a durable
-Workflow run. The tool can wait for a person, webhook, or timer without holding compute, then return
-its result to the model. See [Workflows as tools](/docs/tools/workflows) for the authoring rules and
+Use `defineWorkflowTool` from `eve/tools` to run each call as a durable Workflow run. Its
+executor must start with `"use workflow"` and receives `ctx.agent` and `ctx.ask`. The tool can
+wait for a person, webhook, or timer without holding compute, then return its result to the model. See [Workflows as tools](/docs/tools/workflows) for the authoring rules and
 examples.
 
 ### The `ctx` parameter