eve 0.50.0 → 0.51.1

package/docs/guides/dynamic-capabilities.md

@@ -124,8 +124,8 @@ shadows the session selection for that turn, including when the turn handler
 returns `null`. If a resolver throws or returns an invalid definition, eve logs the
 failure and omits the subagent.
 
-The resolved set applies to local and remote direct delegation and the
-`Workflow` tool. eve
+The resolved set applies to local and remote direct delegation. Background subagents are not
+exposed inside the model-authored `Workflow` tool. eve
 also checks availability again before starting the child, so a stale or
 manually constructed call fails with `SUBAGENT_UNAVAILABLE`. Treat conditional
 availability as capability composition, not as the only authorization

package/docs/guides/frontend/overview.mdx

@@ -87,7 +87,7 @@ Most chat UIs only need `data.messages` and `status`. Drop down to `events` when
 
 `data.messages` are eve-owned `EveMessage[]`. Common text, reasoning, file, and dynamic-tool parts follow the [AI SDK `UIMessage`](https://ai-sdk.dev/docs/reference/ai-sdk-core/ui-message) rendering convention, but the types are not interchangeable. eve also exposes authorization and HITL metadata, and a file part's URL can be absent. Adapt those parts before passing messages to an API typed as `UIMessage[]`.
 
-When the root agent delegates, its stream emits `subagent.called` with the child's `childSessionId`, then `subagent.completed` when the child returns. Detailed child progress lives on the child session's stream instead of being flattened into the root `data.messages`. Use the lower-level [TypeScript client](../client/overview#sessions) to attach to that ID when your UI needs live subagent activity. See [What the parent sees](../../subagents#what-the-parent-sees) for the complete contract.
+When the root agent delegates, its stream emits `subagent.called` with the child's `childSessionId`, then `subagent.completed` after admission with a working task receipt. Later task notifications wake the parent with updates or the final result. Detailed child progress lives on the child session's stream instead of being flattened into the root `data.messages`. Use the lower-level [TypeScript client](../client/overview#sessions) to attach to that ID when your UI needs live subagent activity. See [What the parent sees](../../subagents#what-the-parent-sees) for the complete contract.
 
 ## Sending and streaming
 

package/docs/guides/instrumentation-providers.md

@@ -0,0 +1,242 @@
+---
+title: "Instrumentation Providers"
+description: "Configure the experimental instrumentation provider layout, control captured inputs and outputs, and redact OpenTelemetry spans before export."
+---
+
+Instrumentation providers split observability into files under `agent/instrumentation/`. Each file can handle eve lifecycle events or add an OpenTelemetry destination without owning the rest of the telemetry pipeline.
+
+**This API is experimental and may change without a deprecation period.** Enable it explicitly in `agent.ts`:
+
+```ts title="agent/agent.ts"
+import { defineAgent } from "eve";
+
+export default defineAgent({
+  model: "anthropic/claude-sonnet-5",
+  experimental: {
+    instrumentationProviders: true,
+  },
+});
+```
+
+The provider directory replaces `agent/instrumentation.ts`; the two layouts cannot be used together. See [Observability](./instrumentation) for the default `instrumentation.ts` API.
+
+## Add a provider
+
+The filename identifies the provider slot. Each file must default-export `defineInstrumentation(...)`, an OpenTelemetry integration, or `disableInstrumentation()`.
+
+```text
+agent/instrumentation/
+  audit.ts       lifecycle event provider
+  braintrust.ts  OpenTelemetry destination
+  otel.ts        process-wide OpenTelemetry settings
+```
+
+This provider records action timing and identity without receiving tool arguments or results:
+
+```ts title="agent/instrumentation/audit.ts"
+import { defineInstrumentation } from "eve/instrumentation";
+
+export default defineInstrumentation({
+  events: {
+    "action.started": (event, ctx) => {
+      ctx.state.set({ name: event.name, startedAt: Date.now() });
+    },
+    "action.completed": (event, ctx) => {
+      const started = ctx.state.get() as { name: string; startedAt: number } | undefined;
+      if (started === undefined) return;
+
+      console.log({
+        action: started.name,
+        durationMs: Date.now() - started.startedAt,
+        outcome: event.outcome,
+      });
+    },
+  },
+});
+```
+
+`ctx.state` is JSON storage scoped to this provider and operation. It survives durable suspension and is released after the terminal event.
+
+## Control inputs and outputs
+
+Each provider has an independent `tracePolicy`. It decides whether the provider receives events and whether those events include input or output content.
+
+```ts title="agent/instrumentation/audit.ts"
+import { defineInstrumentation } from "eve/instrumentation";
+
+export default defineInstrumentation({
+  tracePolicy: ({ audience }) => ({
+    emit: true,
+    recordInputs: audience === "public",
+    recordOutputs: audience === "public",
+  }),
+  events: {
+    "model.call.started": (event) => {
+      console.log("input", event.input);
+    },
+    "model.call.completed": (event) => {
+      console.log("output", event.content);
+    },
+  },
+});
+```
+
+The policy receives `agentName`, `audience`, and, when available, `channelType`. `audience` is `"public"`, `"private"`, or `"unknown"`.
+
+The default policy emits metadata for every audience and includes inputs and outputs only for `public` conversations. Return an explicit decision to change that behavior:
+
+| Decision                                      | Result                                                       |
+| --------------------------------------------- | ------------------------------------------------------------ |
+| `false` or `{ emit: false }`                  | Do not invoke this provider for the trace.                   |
+| `true`                                        | Emit the trace with the default audience-aware content rule. |
+| `{ emit: true, recordInputs, recordOutputs }` | Emit the trace with the selected content directions.         |
+
+Inputs include model prompts, tool arguments, channel input, and user responses. Outputs include model responses, tool results, requests for user input, provider metadata, and error details. Content fields are optional on event types because the active policy may remove them.
+
+A provider's policy does not change another provider or the OpenTelemetry pipeline. A policy that throws fails closed for that provider.
+
+## Redact fields in a custom provider
+
+Lifecycle events are immutable snapshots. Copy the fields you need into a destination-specific payload and redact that copy before sending it:
+
+```ts title="agent/instrumentation/audit.ts"
+import { defineInstrumentation } from "eve/instrumentation";
+
+export default defineInstrumentation({
+  tracePolicy: () => ({
+    emit: true,
+    recordInputs: true,
+    recordOutputs: false,
+  }),
+  events: {
+    "action.started": async (event) => {
+      await sendAuditRecord({
+        id: event.idempotencyKey,
+        input: redactApiKey(event.input),
+        kind: event.kind,
+        name: event.name,
+      });
+    },
+  },
+});
+
+function redactApiKey(value: unknown): unknown {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return value;
+
+  const record = value as Record<string, unknown>;
+  return "apiKey" in record ? { ...record, apiKey: "[redacted]" } : record;
+}
+
+async function sendAuditRecord(record: unknown): Promise<void> {
+  // Send the sanitized record to your provider.
+  void record;
+}
+```
+
+Prefer `recordInputs: false` or `recordOutputs: false` when the destination does not need an entire content direction. Use field-level redaction only when the destination needs part of that content.
+
+## Add an OpenTelemetry destination
+
+OpenTelemetry configuration has two parts:
+
+- `otel()` declares process-wide settings such as the resource, sampler, propagators, and trace capture policy. Declare it at most once.
+- `otelIntegration()` adds one destination. Declare one file per exporter or processor chain.
+
+Most agents only need a destination:
+
+```ts title="agent/instrumentation/braintrust.ts"
+import { BraintrustExporter } from "@braintrust/otel";
+import { otelIntegration } from "eve/instrumentation/otel";
+
+export default otelIntegration({
+  traceExporter: new BraintrustExporter({ filterAISpans: true }),
+});
+```
+
+Add `agent/instrumentation/otel.ts` when you need process-wide settings or want to control which content eve writes to OpenTelemetry spans:
+
+```ts title="agent/instrumentation/otel.ts"
+import { otel } from "eve/instrumentation/otel";
+
+export default otel({
+  resource: { "deployment.environment": process.env.VERCEL_ENV ?? "development" },
+  tracePolicy: ({ audience }) => ({
+    emit: true,
+    recordInputs: audience === "public",
+    recordOutputs: audience === "public",
+  }),
+});
+```
+
+The OpenTelemetry `tracePolicy` is a capture ceiling shared by its destinations. A destination cannot restore content excluded by this policy. It does not affect lifecycle event providers created with `defineInstrumentation()`.
+
+## Redact managed OpenTelemetry destinations
+
+`localTraces()` and `agentRuns()` accept an `exportPolicy`. Use the built-in redactors to remove known input or output attributes before that destination's processors receive a span:
+
+```ts title="agent/instrumentation/agent-runs.ts"
+import {
+  agentRuns,
+  composeSpanExportPolicies,
+  redactSpanInputs,
+  redactSpanOutputs,
+} from "eve/instrumentation/otel";
+
+export default agentRuns({
+  exportPolicy: composeSpanExportPolicies(
+    redactSpanInputs(({ audience }) => audience !== "public"),
+    redactSpanOutputs(({ audience }) => audience !== "public"),
+    {
+      attribute: ({ key }) =>
+        key === "user.email" ? { action: "replace", value: "[redacted]" } : { action: "keep" },
+    },
+  ),
+});
+```
+
+`redactSpanInputs()` removes known prompts, instructions, documents, and tool arguments. `redactSpanOutputs()` removes known responses, reasoning, tool results, exception details, event attributes, and status messages. Their optional predicate receives the span name, IDs, attributes, and channel audience.
+
+An export policy can also remove spans or attributes:
+
+```ts
+{
+  span: ({ name }) => name !== "internal.cache.refresh",
+  attribute: ({ key }) =>
+    key === "customer.id" ? { action: "drop" } : { action: "keep" },
+}
+```
+
+Policies run in declaration order. A later policy sees the filtered span produced by earlier policies. Redaction and filtering apply only to that destination and do not mutate spans shared with other destinations.
+
+`recordInputs` and `recordOutputs` remain accepted by `localTraces()` and `agentRuns()` for compatibility, but are deprecated. Use `redactSpanInputs()` and `redactSpanOutputs()` in `exportPolicy` instead.
+
+`otelIntegration()` does not accept `exportPolicy`. Use the process-wide `otel({ tracePolicy })` to limit capture for all custom OpenTelemetry destinations, or supply a destination-specific `SpanProcessor` that filters before its exporter.
+
+## Built-in slots
+
+The provider layout adds two environment-specific defaults:
+
+- `local` records local traces during `eve dev`.
+- `agent-runs` exports to Vercel Agent Runs in production.
+
+Omitting these files preserves the defaults. Reconfigure a slot by exporting `localTraces()` or `agentRuns()` from the matching file. Disable one explicitly:
+
+```ts title="agent/instrumentation/local.ts"
+import { disableInstrumentation } from "eve/instrumentation";
+
+export default disableInstrumentation();
+```
+
+## Lifecycle events
+
+Providers can handle session, channel delivery, turn, model attempt, model call, action, input request, and tool call events. Start and terminal events share an `idempotencyKey`, which can serve as a destination row ID.
+
+An ordinary tool emits both `action.*` and `tool.call.*` events. Use `action.*` for eve's durable dispatch lifecycle, including tools, skills, subagents, and remote agents. Use `tool.call.*` only when you need the AI SDK's in-process tool execution boundary.
+
+Handlers for different providers run concurrently and are failure-isolated. Do not depend on provider execution order. Use `flush` to drain buffered records and `shutdown` to release resources.
+
+## What to read next
+
+- [Observability](./instrumentation): the default `instrumentation.ts` API and trace hierarchy
+- [Local development](./dev-tui): inspect local traces in the TUI
+- [Hooks](./hooks): react to runtime events outside the instrumentation provider API

package/docs/guides/instrumentation.md

@@ -7,6 +7,8 @@ description: "Trace an agent with OpenTelemetry in instrumentation.ts, read the
 
 If you intend to export telemetry, review the exporter destination, data categories, and required legal approvals before enabling telemetry.
 
+**The instrumentation provider API is experimental and off by default.** Enable `experimental.instrumentationProviders` to use its one-file-per-provider layout, directional content capture, and per-destination redaction. See [Instrumentation Providers](./instrumentation-providers) for setup and current limitations.
+
 ## Three observability surfaces
 
 eve observes an agent through three distinct surfaces. They do not all live in this file, and they write to different places:

package/docs/guides/meta.json

@@ -4,6 +4,7 @@
     "deployment",
     "auth-and-route-protection",
     "instrumentation",
+    "instrumentation-providers",
     "hooks",
     "session-context",
     "dynamic-capabilities",

package/docs/guides/remote-agents.md

@@ -1,6 +1,6 @@
 ---
 title: "Remote Agents"
-description: "Call another eve deployment as a subagent with defineRemoteAgent: same tool call as a local subagent, outbound auth, durable callback dispatch."
+description: "Call another eve deployment as a subagent with defineRemoteAgent: the same tool call as a local subagent, with outbound auth and durable callbacks."
 ---
 
 `defineRemoteAgent` calls a separately deployed eve agent as if it were a local subagent. Reach for it when the specialist you delegate to is a separately owned agent behind its own URL rather than a directory in your repo.
@@ -33,7 +33,7 @@ export default defineRemoteAgent({
 ## Dynamic remote agents
 
 Wrap the file in `defineDynamic` when the target or its availability depends on
-the current session. Return `defineRemoteAgent(...)` to expose it and nil to
+the current session. Return `defineRemoteAgent(...)` to expose it and `null` to
 omit it:
 
 ```ts title="agent/subagents/weather.ts"
@@ -82,7 +82,7 @@ The function may be async and must return a non-empty string. `auth` and `header
 
 To the model, a remote agent is another subagent tool. You call it the same way you call a local subagent, with a `message` and an optional `outputSchema`. The message must carry the full task, including any context the remote agent needs, because it never receives the parent's conversation history.
 
-To require structured output, set an `outputSchema` on the agent definition for fresh delegations or on an individual call for that turn. The structured value becomes the tool result, and the remote child remains available for follow-up messages. See [Subagents](../subagents) for continuation behavior.
+To require structured output, set an `outputSchema` on the agent definition for fresh delegations or on an individual call for that turn. The structured value arrives in the task's completion notification, and the remote child remains available for follow-up messages. See [Subagents](../subagents) for continuation behavior.
 
 ## Outbound auth
 
@@ -170,22 +170,21 @@ Missing, malformed, duplicate, unsampled, untrusted, and mixed-version assertion
 
 ## How remote dispatch and callbacks work
 
-A local subagent runs inline. A remote one runs in its own deployment, so dispatch is asynchronous:
+A remote subagent runs as a durable background task in its own deployment:
 
 1. The parent starts a persistent conversation session on the remote's `POST /eve/v1/session`, passing a framework callback URL.
-2. The parent turn parks (suspends durably without holding compute; see [Execution model & durability](../concepts/execution-model-and-durability)) until the remote posts a terminal callback.
-3. When the callback arrives, the parent resumes and surfaces the result.
+2. The call returns `{ status: "working", taskId, agentId }` after the remote accepts the child.
+3. The callback later settles the task and sends a task notification to the parent.
 
 The parent stream carries the same `subagent.called`, `action.result`, and `subagent.completed` events as local delegation. For a remote call, `subagent.called.data.remote.url` records the target.
 
-Cancelling the parent while a remote call is active sends an authenticated `POST /eve/v1/session/:childSessionId/cancel` to the remote and waits for that request to be accepted before the parent settles. eve resolves the remote's `headers` and `auth` again for every cancellation attempt, so rotating credentials work the same way as they do for session creation. Cancellation always uses the standard eve cancel path on `url`, even when `path` customizes only the create-session endpoint. The remote child reports `turn.cancelled` → `session.waiting` on its own stream; an older or unreachable remote is logged but cannot turn the parent's cancellation into a failure.
+An admitted task 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. eve resolves the remote's `headers` and `auth` again for every cancellation attempt, so rotating credentials work the same way as they do for session creation. Cancellation always uses the standard eve cancel path on `url`, even when `path` customizes only the create-session endpoint. The remote child reports `turn.cancelled` → `session.waiting` on its own stream; an older or unreachable remote is logged but cannot turn the parent's cancellation into a failure.
 
 When the parent session ends, eve sends an authenticated `POST /eve/v1/session/:childSessionId/reset` for each remote child. Reset retires the parked remote session and recursively cleans up its descendants. The request uses freshly resolved `headers` and `auth`; failures are logged so an unreachable remote cannot block parent finalization.
 
-Both failure paths surface to the parent as a failed tool result, so the caller can explain or recover within the same session. A failed _start_ returns the error inline. A remote that starts and then fails posts a terminal failure callback, which the parent receives as an errored subagent result carrying the remote's error (or `REMOTE_AGENT_FAILED` when none is supplied). Terminal callback delivery runs as a durable step on the underlying workflow engine (see [Execution model & durability](../concepts/execution-model-and-durability)). A failed callback POST is rethrown rather than marking the task complete, so the engine retries it.
+A failed _start_ rejects admission before a task receipt is returned. After a remote starts, a terminal failure callback fails the task and notifies the parent with the remote's error (or `REMOTE_AGENT_FAILED` when none is supplied). Terminal callback delivery runs as a durable step on the underlying workflow engine (see [Execution model & durability](../concepts/execution-model-and-durability)). A failed callback POST is rethrown rather than marking the task complete, so the engine retries it.
 
 ## What to read next
 
 - Local delegation and the isolation boundary → [Subagents](../subagents)
-- Have the model orchestrate remote agents programmatically → [Workflow tool](../concepts/built-in-tools#workflow-tool)
 - Securing the receiving deployment → [Auth & route protection](./auth-and-route-protection)

package/docs/memory/overview.mdx

@@ -211,7 +211,7 @@ The namespace separates an application's memory domains before scope is
 applied. Omit it to use `defaultNamespace`, which combines the slot name, the
 graph node, and a deployment-aware identity:
 
-- Production and other Vercel environments use the project and environment.
+- Production and other Vercel environments use the project and environment. Members of a top-level `agents/` workspace use separate namespaces.
 - Preview also uses the branch or deployment identity.
 - Local development uses a digest of the application root, never the raw path.
 

package/docs/reference/cli.md

@@ -3,7 +3,7 @@ title: "CLI"
 description: "Reference for every eve CLI command: init, set, info, build, start, dev, logs, trace, link, deploy, eval, channels, and extension."
 ---
 
-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.
+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.
 
 ## Commands
 
@@ -37,7 +37,7 @@ When `eve build` fails on discovery errors, it prints the full diagnostics repor
 ## `eve init`
 
 ```bash
-eve init [target] [--model <provider/model-id>] [--reasoning <effort>] [--channel-web-nextjs]
+eve init [target] [--agents <name,...>] [--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,6 +48,8 @@ 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.
 
@@ -55,6 +57,7 @@ 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.                     |

package/docs/sandbox.mdx

@@ -156,7 +156,9 @@ With `backend` omitted, eve uses `defaultBackend()`, which resolves on first use
 3. **microsandbox** when the host supports it: macOS on Apple Silicon, or glibc Linux with KVM enabled.
 4. **just-bash** as the dependency-free fallback.
 
-By default, Docker and microsandbox pull `ghcr.io/vercel/eve` while Vercel Sandbox pulls `vcr.vercel.com/vercel/eve/base`. Each image tag matches the installed eve version. Set `EVE_SANDBOX_IMAGE_TAG` to replace the version-derived tag for these default images. An explicit `image` passed to `docker()` or `microsandbox()` still takes precedence.
+By default, Docker and microsandbox pull `ghcr.io/vercel/eve` while Vercel Sandbox pulls `vcr.vercel.com/vercel/eve/base`. Each image tag matches the installed eve version. Set `EVE_SANDBOX_IMAGE_TAG` to replace the version-derived tag for these default images. An explicit `image` passed to `docker()`, `microsandbox()`, or `vercel()` takes precedence. A snapshot `source` on `vercel()` takes precedence over its `image` because Vercel Sandbox treats them as mutually exclusive.
+
+On every backend, authored commands run as the non-root `vercel-sandbox` user through a non-interactive `bash -lc` login shell. `/workspace` and `$HOME` are writable, `$HOME/.local/bin` is on `PATH` for user-scoped executables, and system paths such as `/usr/local` stay root-owned. Use passwordless `sudo` when setup genuinely needs system-wide changes; `sudo` resets the environment, so pass through variables like `NPM_CONFIG_PREFIX` explicitly if a privileged step depends on them.
 
 `defaultBackend()` also accepts a keyed bag so each inner backend gets its own typed create options:
 

package/docs/subagents/index.mdx

@@ -17,7 +17,7 @@ The root session receives `agent` by default. The model calls it to delegate a t
 }
 ```
 
-The copy uses the root's instructions, connections, auth, and sandbox. It receives the same tools except for the root-only `agent` and `Workflow`, and starts with fresh conversation history and fresh state. Its file writes are immediately visible to the root. To run independent tasks in parallel, emit multiple `agent` calls in one response; eve runs the batch concurrently and returns every result before the root continues. 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 `Workflow`, 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 updates or the final result. 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.
 
@@ -46,7 +46,9 @@ export default defineAgent({
 });
 ```
 
-`description` is required. The parent reads it to decide whether to delegate, so the compiler rejects any subagent whose `agent.ts` leaves it out.
+`description` is required. The parent reads it to decide whether to delegate, so the compiler rejects any subagent whose `agent.ts` leaves it out. 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 updates, completion, failure, or cancellation. Human input requests surface separately on the parent session.
+
+A child running as a background task receives the framework `task_update` tool. It uses `task_update` to report progress to its parent. `task_cancel` is available to sessions that own background tasks, including a child that starts nested background work.
 
 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.
 
@@ -54,7 +56,7 @@ A mounted extension can also contribute declared subagents from `extension/subag
 
 To expose a declared subagent only for certain sessions or turns, export
 `defineDynamic` from that subagent's `agent.ts`. Return a `defineAgent`
-configuration to expose the subagent, or nil to omit it from the parent's tools.
+configuration to expose the subagent, or `null` to omit it from the parent's tools.
 
 ```ts title="agent/subagents/researcher/agent.ts"
 import { defineAgent, defineDynamic } from "eve";
@@ -73,9 +75,9 @@ export default defineDynamic({
 ```
 
 Resolvers run at `session.started` or `turn.started`; `step.started` is not
-supported for subagents. A nil result (`null` or `undefined`) removes the
+supported for subagents. A nullish result (`null` or `undefined`) removes the
 subagent's description and tool definition from the model-visible surface.
-The subagent's filesystem manifest is always compiled; a non-nil result injects
+The subagent's filesystem manifest is always compiled; a non-nullish result injects
 the returned agent configuration when the child runs.
 
 Packaging controls must be available before the resolver runs. Put them on
@@ -151,7 +153,7 @@ eve lowers every subagent visible to the current agent (the root built-in copy,
 
 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.
 
-`Workflow` is also root-only. Child sessions can still call their own declared or remote subagents, but they receive neither `Workflow` nor the built-in `agent`. The Workflow tool's `maxSubagents` option caps the number of calls made by one program (default 100); see [Workflow tool](./concepts/built-in-tools#workflow-tool).
+Child sessions can still call their own declared or remote subagents, but they receive neither `Workflow` nor the built-in `agent`. Background subagents run through the model tool loop and are not available inside a model-authored `Workflow` program.
 
 A directly declared subagent's tool name is the bare path-derived name, with no prefix. `agent/subagents/researcher/` registers as the tool `researcher`. A subagent supplied by a mounted extension includes the mount namespace, such as `crm__reviewer`. The model, approvals, logs, and evals reference the resulting name. Its input schema is:
 
@@ -169,7 +171,7 @@ Do not rely on subagent delegation by itself as an approval boundary. Put sensit
 
 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, read `subagent.called.data.childSessionId` and subscribe at `GET /eve/v1/session/:childSessionId/stream`.
 
-Cancelling a parent turn also requests cancellation of every active child it started, recursively through nested and remote subagents. Each affected session emits its own `turn.cancelled` → `session.waiting` boundary; the cancelled parent does not synthesize tool results or emit `subagent.completed`. A child that already completed or parked has no active turn and is a benign no-op.
+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. 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 so completed earlier steps, tool results, and sandbox work remain available to the child. 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.
 
@@ -188,4 +190,3 @@ Split out a subagent when the task needs a different prompt or specialist role,
 ## What to read next
 
 - [Remote agents](./guides/remote-agents): call another eve deployment as a subagent.
-- [Workflow tool](./concepts/built-in-tools#workflow-tool): have the model orchestrate its subagents programmatically (fan-out, map-reduce).

package/docs/tools/overview.mdx

@@ -56,15 +56,16 @@ 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.
 
-### Experimental background execution
+### 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.
-The root agent must enable `experimental.tasks`; eve rejects background tools at build time otherwise.
+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.
 
-This contract currently supports framework-owned task executors, including local and remote
-subagents when `experimental.tasks` is enabled. After delegating, an in-process executor reports
+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
@@ -78,12 +79,12 @@ 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.
 
-### Durable tools
+### Workflows as tools
 
-A tool whose `execute` starts with `"use workflow"` runs as a durable Workflow run instead of
-inside the model step. It can wait for a person, a webhook, or a timer for as long as it takes, with
-nothing running in between, and its return value still settles the tool call. See
-[Durable tools](/docs/tools/workflows).
+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
+examples.
 
 ### The `ctx` parameter