eve 0.71.3 → 0.72.0

package/docs/evals/judge.mdx

@@ -1,9 +1,9 @@
 ---
 title: "Judge"
-description: "Grade evals with evaluation models using criteria, typed questions, or batches, and set thresholds on each assertion."
+description: "Grade evals with decision models using criteria, typed questions, or batches, and set thresholds on each assertion."
 ---
 
-Use `t.judge(...)` when a deterministic [assertion](./assertions) cannot capture what a good response looks like. It calls [`evaluate` from `eve/ai`](../guides/evaluate#evaluate-inside-a-tool) and defaults to `typesafe-ai/jev`, TypeSafe AI's [Jev evaluation model](https://vercel.com/i/what-is-jev). The judge is separate from the agent under test and is used only for scoring.
+Use `t.judge(...)` when a deterministic [assertion](./assertions) cannot capture what a good response looks like. It calls [`decide` from `eve/ai`](../guides/decide#decide-inside-a-tool) and defaults to `typesafe-ai/jev`, TypeSafe AI's [Jev decision model](https://vercel.com/i/what-is-jev). The judge is separate from the agent under test and is used only for scoring.
 
 ```ts
 import { defineEval } from "eve/evals";
@@ -17,7 +17,7 @@ export default defineEval({
 });
 ```
 
-No judge configuration is required. Configure credentials for the evaluator as described under [Configuring the judge model](#configuring-the-judge-model).
+No judge configuration is required. Configure credentials for the decider as described under [Configuring the judge model](#configuring-the-judge-model).
 
 ## The graders
 
@@ -41,11 +41,11 @@ t.judge({
   .atLeast(0.75);
 ```
 
-Choice questions require an `expected` option key. eve uses that expectation locally for scoring; it does not send it to the evaluator. Instructions and rubric descriptions accept strings, JSON objects, or JSON arrays. Descriptions can also be `null`.
+Choice questions require an `expected` option key. eve uses that expectation locally for scoring; it does not send it to the decider. Instructions and rubric descriptions accept strings, JSON objects, or JSON arrays. Descriptions can also be `null`.
 
 ## Choose the value to grade
 
-By default, the evaluator receives `{ input, output }`: the latest prompt and assistant message from the session whose turn most recently settled. Approval responses and stream reads preserve that prompt. For multipart messages, including `session.sendFile()`, the prompt contains the text parts.
+By default, the decider receives `{ input, output }`: the latest prompt and assistant message from the session whose turn most recently settled. Approval responses and stream reads preserve that prompt. For multipart messages, including `session.sendFile()`, the prompt contains the text parts.
 
 Pass `on` to replace the output. JSON values stay structured rather than being converted to strings:
 
@@ -66,9 +66,9 @@ t.judge("The assistant remembers the user's favorite word across turns.", {
 
 The transcript contains user and assistant messages in turn order, excluding reasoning, tool calls, and tool results. See [Multi-turn evals](./cases#multi-turn-evals).
 
-## Evaluate several questions together
+## Decide several questions together
 
-A batch makes one evaluation request against one shared state. Pass `state` to replace the default `{ input, output }` completely. Batch calls use `state` instead of `on`.
+A batch makes one decision request against one shared state. Pass `state` to replace the default `{ input, output }` completely. Batch calls use `state` instead of `on`.
 
 ```ts
 const judgments = t.judge({
@@ -120,9 +120,9 @@ Model settings resolve in this order:
 1. Per-call: `t.judge("…", { model, modelOptions })`.
 2. Per-eval: `defineEval({ judge: { model, modelOptions }, test })`.
 3. Project default: `defineEvalConfig({ judge: { model, modelOptions } })`.
-4. The default model used by `evaluate`, currently `typesafe-ai/jev`.
+4. The default model used by `decide`, currently `typesafe-ai/jev`.
 
-A per-eval `judge` replaces the project's judge configuration. Per-call fields override the resolved configuration. `judge` and its `model` are optional; deterministic evals make no evaluation requests.
+A per-eval `judge` replaces the project's judge configuration. Per-call fields override the resolved configuration. `judge` and its `model` are optional; deterministic evals make no decision requests.
 
 ```ts title="evals/evals.config.ts"
 import { defineEvalConfig } from "eve/evals";
@@ -132,30 +132,30 @@ export default defineEvalConfig({
 });
 ```
 
-String IDs resolve through the AI SDK default provider, or Vercel AI Gateway when none is configured. Gateway uses `AI_GATEWAY_API_KEY` or Vercel OIDC credentials; eve's existing local Gateway connection is also honored by `evaluate`. An explicit provider evaluation model uses that provider's credentials:
+String IDs resolve through the AI SDK default provider, or Vercel AI Gateway when none is configured. Gateway uses `AI_GATEWAY_API_KEY` or Vercel OIDC credentials; eve's existing local Gateway connection is also honored by `decide`. An explicit provider decision model uses that provider's credentials:
 
 ```ts
 import { openai } from "@ai-sdk/openai";
 
 t.judge("The response addresses the request.", {
-  model: openai.evaluationModel("gpt-6-luna"),
+  model: openai.decisionModel("gpt-6-luna"),
   modelOptions: { providerOptions: { openai: { reasoningEffort: "high" } } },
 });
 ```
 
-Use the provider's `evaluationModel` factory, not a language model instance. AI SDK supplies evaluation adapters for supported language models. Provider support and the evaluation contract are experimental; see [AI SDK evaluation](https://ai-sdk.dev/docs/ai-sdk-core/evaluation).
+Use the provider's `decisionModel` factory, not a language model instance. AI SDK supplies decision adapters for supported language models. Provider support and the decision contract are experimental; see [AI SDK decision](https://ai-sdk.dev/docs/ai-sdk-core/decisions).
 
-String model IDs resolve through the default provider's evaluation API. Gateway accepts native evaluation models such as `typesafe-ai/jev`; passing a language model ID such as `openai/gpt-6-luna` does not automatically select the OpenAI adapter. Use an evaluation-model instance as shown above for language models.
+String model IDs resolve through the default provider's decision API. Gateway accepts native decision models such as `typesafe-ai/jev`; passing a language model ID such as `openai/gpt-6-luna` does not automatically select the OpenAI adapter. Use a decision-model instance as shown above for language models.
 
-Missing credentials, invalid answers, unsupported question types, and provider errors become failed gates even for tracked-only judgments. They do not silently skip the eval or select another model. Validation, authentication, and retries use the shared `evaluate` implementation.
+Missing credentials, invalid answers, unsupported question types, and provider errors become failed gates even for tracked-only judgments. They do not silently skip the eval or select another model. Validation, authentication, and retries use the shared `decide` implementation.
 
 ## Diagnostics and migration
 
-Reports use `judge.boolean`, `judge.score`, and `judge.choice`; batch assertion names also include their question key. Diagnostics include the captured state, question, and raw answer. Assertion metadata retains the normalized score, model identity, token usage, warnings, and available provider and response metadata. Usage for a batch is marked as shared across its assertions, not a separate charge for each question. Evaluation models do not promise a prose rationale.
+Reports use `judge.boolean`, `judge.score`, and `judge.choice`; batch assertion names also include their question key. Diagnostics include the captured state, question, and raw answer. Assertion metadata retains the normalized score, model identity, token usage, warnings, and available provider and response metadata. Usage for a batch is marked as shared across its assertions, not a separate charge for each question. Decision models do not promise a prose rationale.
 
 The autoevals graders have been removed. Replace `t.judge.autoevals.closedQA(criteria, options)` with `t.judge(criteria, options)`. Scores now represent a probability rather than a binary yes/no answer, so review thresholds against your examples. For factuality, summaries, or SQL equivalence, write an explicit question and include the reference in shared state. No old grader buckets are preserved.
 
-Change configured language model instances to evaluation model instances. `modelOptions.providerOptions`, assertion labels, and threshold methods remain available. [Braintrust reporting](./reporters) continues to accept judge scores independently of the grader implementation.
+Change configured language model instances to decision model instances. `modelOptions.providerOptions`, assertion labels, and threshold methods remain available. [Braintrust reporting](./reporters) continues to accept judge scores independently of the grader implementation.
 
 ## What to read next
 

package/docs/evals/overview.mdx

@@ -56,7 +56,7 @@ export default defineEvalConfig({
 });
 ```
 
-Everything is optional. `judge` sets the default model for [LLM-as-judge](./judge) assertions (`t.judge(...)`); omit it to use the default evaluator, `typesafe-ai/jev`. Deterministic evals make no judge requests. `reporters`, `maxConcurrency`, and `timeoutMs` round out the defaults. Config `reporters` observe every eval in the run, so set one `Braintrust()` here instead of adding it to each eval. CLI flags (`--max-concurrency`, `--timeout`) and per-eval values take precedence over the config defaults.
+Everything is optional. `judge` sets the default model for [LLM-as-judge](./judge) assertions (`t.judge(...)`); omit it to use the default decider, `typesafe-ai/jev`. Deterministic evals make no judge requests. `reporters`, `maxConcurrency`, and `timeoutMs` round out the defaults. Config `reporters` observe every eval in the run, so set one `Braintrust()` here instead of adding it to each eval. CLI flags (`--max-concurrency`, `--timeout`) and per-eval values take precedence over the config defaults.
 
 ### Run setup and teardown
 

package/docs/guides/{evaluate.md → decide.md}

@@ -1,21 +1,21 @@
 ---
 title: Automatic Model Selection
-description: "Choose agent models automatically or evaluate typed questions in your tools and application code."
+description: "Choose agent models automatically or ask typed questions in your tools and application code."
 ---
 
 Use `auto` from `eve/models` to choose an agent model from an allowlist before
-inference begins. It uses the [AI SDK evaluation API](https://ai-sdk.dev/docs/ai-sdk-core/evaluation),
-so the evaluator can be a Vercel AI Gateway model ID or an evaluation model from
-an installed provider. Use `evaluate` from `eve/ai` to ask typed questions in
+inference begins. It uses the [AI SDK decision API](https://ai-sdk.dev/docs/ai-sdk-core/decisions),
+so the decider can be a Vercel AI Gateway model ID or a decision model from
+an installed provider. Use `decide` from `eve/ai` to ask typed questions in
 your own tools or application code.
 
-The AI SDK evaluation model specification is experimental and can change in
+The AI SDK decision model specification is experimental and can change in
 patch releases.
 
 ## Choose from Gateway models
 
-By default, `auto` evaluates with `typesafe-ai/jev`, TypeSafe AI's
-[Jev evaluation model](https://vercel.com/i/what-is-jev). Like other AI SDK
+By default, `auto` decides with `typesafe-ai/jev`, TypeSafe AI's
+[Jev decision model](https://vercel.com/i/what-is-jev). Like other AI SDK
 model strings, it uses Vercel AI Gateway unless the application has configured a
 different global default provider.
 
@@ -35,13 +35,13 @@ export default defineAgent({
 
 Configure Gateway authentication as you would for any other AI SDK model. eve
 does not add a TypeSafe credential or transport layer. During `eve dev`, a
-Gateway evaluator uses the same connection selected through `/login` as Gateway
+Gateway decider uses the same connection selected through `/login` as Gateway
 language models. A configured AI SDK default provider still owns string model
 resolution during development. The TUI footer displays `dynamic model` when the
 agent uses `auto`, then adds the resolved model for the current turn, such as
 `dynamic model · openai/gpt-6-luna`.
 
-Set `fallback` to keep the turn running when the evaluator is unavailable or
+Set `fallback` to keep the turn running when the decider is unavailable or
 returns an error. The fallback can be a Gateway model ID, an AI SDK language
 model instance, or an object with `model` and a `reasoning` override:
 
@@ -60,15 +60,15 @@ export default defineAgent({
 });
 ```
 
-The fallback applies only to evaluator failures. eve logs a warning with the
-evaluator error and fallback identity when it switches models. Invalid prompts,
+The fallback applies only to decider failures. eve logs a warning with the
+decider error and fallback identity when it switches models. Invalid prompts,
 including requests without user text or with a latest message over the routing
-limit, still fail before evaluator I/O. Cancelling the turn also aborts routing
+limit, still fail before decider I/O. Cancelling the turn also aborts routing
 instead of selecting the fallback.
 
 ## Use a provider directly
 
-Install the provider package yourself and pass its evaluation model. The provider
+Install the provider package yourself and pass its decision model. The provider
 owns its credentials and settings.
 
 ```sh
@@ -82,7 +82,7 @@ import { auto } from "eve/models";
 
 export default defineAgent({
   model: auto({
-    model: typeSafeAi.evaluationModel("jev-latest"),
+    model: typeSafeAi.decisionModel("jev-latest"),
     options: {
       "openai/gpt-6-sol": "Difficult reasoning and engineering tasks",
       "openai/gpt-6-luna": "Routine tasks where fast completion matters",
@@ -91,12 +91,12 @@ export default defineAgent({
 });
 ```
 
-Any provider that implements the AI SDK `Experimental_EvaluationModel` contract
+Any provider that implements the AI SDK `Experimental_DecisionModel` contract
 works here.
 
 ## Route to provider models and set reasoning
 
-An option's key is the value shown to the evaluator. A string value describes a
+An option's key is the value shown to the decider. A string value describes a
 Gateway model whose ID is the key. Use the object form when the selected model is
 a provider instance, an alias, or needs a reasoning override.
 
@@ -120,7 +120,7 @@ export default defineAgent({
 });
 ```
 
-The evaluator sees option keys, descriptions, and recent text messages. It never
+The decider sees option keys, descriptions, and recent text messages. It never
 receives provider credentials or serialized language model instances. When it
 selects `my_secret_model`, eve resolves the key back to the authored Anthropic
 model.
@@ -129,16 +129,16 @@ Supported reasoning values are `"provider-default"`, `"none"`, `"minimal"`,
 `"low"`, `"medium"`, `"high"`, and `"xhigh"`. An omitted value inherits the
 agent's reasoning setting.
 
-## Evaluate inside a tool
+## Decide inside a tool
 
-Use `evaluate` to ask choice, score, or boolean questions about the state you pass to it.
+Use `decide` to ask choice, score, or boolean questions about the state you pass to it.
 It defaults to `typesafe-ai/jev` and uses the same authentication as `auto`,
 including the Gateway connection selected through `/login` during `eve dev`.
-Pass `model` to use another evaluation model ID or a provider instance. A configured
+Pass `model` to use another decision model ID or a provider instance. A configured
 AI SDK default provider takes precedence over the local Gateway connection.
 
 ```ts title="agent/tools/classify-request.ts"
-import { evaluate } from "eve/ai";
+import { decide } from "eve/ai";
 import { defineTool } from "eve/tools";
 import { z } from "zod";
 
@@ -146,7 +146,7 @@ export default defineTool({
   description: "Choose the team that can help with a customer request.",
   inputSchema: z.object({ request: z.string().min(1).max(8000) }),
   async execute({ request }, ctx) {
-    const result = await evaluate({
+    const result = await decide({
       state: { request },
       questions: {
         team: {
@@ -169,23 +169,23 @@ The choice above is typed as `"billing" | "support"`. Each question appears unde
 its authored key in `result.answers`. Results also include token usage, warnings,
 provider metadata, and response metadata. To use that choice to delegate while keeping specialist subagents out of the parent model's tools, see [Route to a hidden subagent with Jev](/docs/tools/workflows#route-to-a-hidden-subagent-with-jev).
 
-`evaluate` accepts AI SDK evaluation options, including `maxRetries`, `headers`,
+`decide` accepts AI SDK decision options, including `maxRetries`, `headers`,
 and `providerOptions`. Pass an `abortSignal` to cancel the request. Input and
 answer validation, retries, and provider errors follow AI SDK semantics.
 
-You can also call `evaluate` outside a tool; it does not require an active eve
-session. Each call performs its own evaluation. `auto` uses this function
+You can also call `decide` outside a tool; it does not require an active eve
+session. Each call performs its own decision. `auto` uses this function
 and adds the per-turn routing behavior described below.
 
 ## Judge eval results
 
-Eval authors can use `t.judge(...)` to turn evaluation answers into scored assertions, including batches of questions sharing one state. It uses this same `evaluate` implementation and default model. See [Judge](../evals/judge) for criteria, rubrics, and thresholds.
+Eval authors can use `t.judge(...)` to turn decision answers into scored assertions, including batches of questions sharing one state. It uses this same `decide` implementation and default model. See [Judge](../evals/judge) for criteria, rubrics, and thresholds.
 
-## Evaluate tool approvals
+## Decide tool approvals
 
-Use `auto({ model? })` when an evaluation model should decide whether a
+Use `auto({ model? })` when a decision model should decide whether a
 tool call can run automatically or needs human approval. It accepts the same
-AI SDK evaluation model strings and provider instances described above and
+AI SDK decision model strings and provider instances described above and
 defaults to `typesafe-ai/jev`:
 
 ```ts title="agent/tools/deploy.ts"
@@ -201,7 +201,7 @@ export default defineTool({
 });
 ```
 
-The evaluation model reviews the tool name and input for dangerous effects. A
+The decision model reviews the tool name and input for dangerous effects. A
 caution, failed review, or incomplete input requires human approval. See
 [Human-in-the-loop approvals](/docs/human-in-the-loop#approvals) for classifier
 options and data handling, and the
@@ -210,17 +210,17 @@ guide for an end-to-end walkthrough.
 
 ## Runtime behavior
 
-`auto` evaluates at the first `step.started` event, after the incoming prompt
+`auto` decides at the first `step.started` event, after the incoming prompt
 is available and before the selected language model runs. It reuses that choice
 for later tool-loop steps in the same turn. A new turn makes a new choice, and
 child sessions route from their own prompts.
 
-The evaluator receives up to eight recent user and assistant text messages,
+The decider receives up to eight recent user and assistant text messages,
 capped at 16,000 characters. Requests without user text and latest messages over
 the limit fail before provider I/O.
 
-Evaluation validation, retries, provider errors, and model resolution follow AI
-SDK semantics. Without `fallback`, an evaluator error fails the turn. With
+Decision validation, retries, provider errors, and model resolution follow AI
+SDK semantics. Without `fallback`, a decider error fails the turn. With
 `fallback`, eve uses and retains that model for the rest of the turn. Cancelling
-the active turn aborts evaluation and prevents a routed or fallback choice from
+the active turn aborts decision and prevents a routed or fallback choice from
 being retained.

package/docs/guides/dynamic-capabilities.md

@@ -362,7 +362,7 @@ A dynamic connection, tool, or skill whose name matches an **authored** one **ov
 
 At `turn.started`, model, tool, skill, and subagent resolvers receive the visible conversation history and incoming message in `ctx.messages`, oldest first. Request context is included, and history projection still applies. Read these messages from the handler's second argument; the event itself contains turn metadata. Instruction resolvers use the separate snapshot described under [Dynamic instructions](#dynamic-instructions).
 
-A message that steers a held turn, or waits behind its session-limit prompt, joins that turn instead of starting one, as does a completed sign-in, so `turn.started` resolvers do not see it; `step.started` resolvers do. When memory recall runs, its results appear in the projected snapshot before incoming input.
+A message that steers a held turn joins it without another `turn.started`, as does a completed sign-in, so `turn.started` resolvers do not see it; `step.started` resolvers do. A message sent while a session-limit prompt waits starts its own turn, so `turn.started` resolvers see it, and that turn waits for the prompt's answer before the model runs. When memory recall runs, its results appear in the projected snapshot before incoming input.
 
 ### Execution order
 

package/docs/guides/frontend/overview.mdx

@@ -174,7 +174,9 @@ supplied `session` remains externally owned and is never replaced by prewarming
 
 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 `task.started` for the call, `agent.started` with the child's `sessionId`, and `task.settled` with the call's result, failure, or cancellation. The default reducer settles the subagent's tool part from `task.settled`, so the part shows the call's outcome rather than its start receipt. `data.tasks[taskId].calls[callId]` records each call's `status`, `output`, and `error`, and `data.agents[sessionId]` records each session a call opened, with its `taskId` and opening `callId`. These records come from the root stream alone.
+A tool part's `state` comes from the shared lifecycle interpretation of the event stream. Its events supply input, output, and error text. A call waiting on an approval or a question reads `approval-requested` until the stream settles the request. An answer you submit doesn't change the part until then. `toolCallState(conversation, callId)` reads tool-call status, including task cancellation and calls interrupted without a result. The full event projection remains internal; `ConversationState` retains its messages, turns, inputs, tasks, and agent sessions.
+
+When the root agent delegates, its stream emits `task.started` for the call, `agent.started` with the child's `sessionId`, and `task.settled` with the call's result, failure, or cancellation. The default reducer keeps the subagent's tool part running until `task.settled` arrives and then settles it with the call's outcome; the start receipt never settles it. `data.tasks[taskId].calls[callId]` records each call's `status`, `output`, and `error`, and `data.agents[sessionId]` records each session a call opened, with its `taskId` and opening `callId`. These records come from the root stream alone.
 
 Detailed child progress lives on the child session's stream, not in the root `data.messages`. Pass `followSubagents: true` to follow the session each subagent call reaches while the component is mounted; following is off by default. Narrow `data.agents[sessionId].observation.status` before reading its `conversation`: `"not-followed"` has no child detail, `"following"` has live detail, and `"idle"` has everything the calls so far produced and resumes when another call reaches the task. `"unavailable"` means the stream failed, not that the child failed. Calls that continue a task with its `taskId` reach the same session, so one session's `conversation.messages`, `inputs`, and `turns` span all of them. Sessions that a custom task opens with `ctx.agent` are recorded but not followed.
 

package/docs/guides/hooks.md

@@ -227,7 +227,7 @@ The remaining subscribers for the event still run. Then eve cancels the turn the
 
 Subagents may carry their own `agent/hooks/` directory. Subagent hooks fire only inside the subagent scope. Parent-agent hooks do not fire for subagent turns, and subagent hooks see only the subagent's own context.
 
-Interactive events such as `input.requested` and `authorization.required` are also published on the parent stream. Parent hooks observe these events after the parent channel handler and stream write, with the parent's session, agent, and channel context. The event retains the child's turn coordinates, so `event.data.turnId` can differ from `ctx.session.turn.id`. The parent follows a proxied `input.requested` or `authorization.required` with `turn.waiting` for its own open turn, which stays open until the running call finishes. A proxied `authorization.completed` is not followed by a parent turn event. These parent events also invoke parent hooks; they do not resolve pending input requests.
+Interactive events such as `input.requested` and `authorization.required` are also published on the parent stream. Parent hooks observe these events after the parent channel handler and stream write, with the parent's session, agent, and channel context. The event retains the child's turn coordinates, so `event.data.turnId` can differ from `ctx.session.turn.id`. A proxied `input.requested` also carries `event.data.callId`, the parent call that waits on it. The parent follows a proxied `input.requested` or `authorization.required` with `turn.waiting` for its own open turn, which stays open until the running call finishes. A proxied `authorization.completed` is not followed by a parent turn event. These parent events also invoke parent hooks; they do not resolve pending input requests.
 
 ## Hook vs tool vs provider
 

package/docs/guides/instrumentation/instrumentation.mdx

@@ -23,7 +23,7 @@ agent/instrumentation/
   audit.ts  lifecycle instrumentation
 ```
 
-This instrumentation records action timing and identity without receiving tool
+This instrumentation records tool timing and identity without receiving tool
 arguments or results:
 
 ```ts title="agent/instrumentation/audit.ts"
@@ -31,15 +31,15 @@ import { defineInstrumentation } from "eve/instrumentation";
 
 export default defineInstrumentation({
   events: {
-    "action.started": (event, ctx) => {
-      ctx.state.set({ name: event.name, startedAt: Date.now() });
+    "tool.call.started": (event, ctx) => {
+      ctx.state.set({ name: event.toolName, startedAt: Date.now() });
     },
-    "action.completed": (event, ctx) => {
+    "tool.call.completed": (event, ctx) => {
       const started = ctx.state.get() as { name: string; startedAt: number } | undefined;
       if (started === undefined) return;
 
       console.log({
-        action: started.name,
+        tool: started.name,
         durationMs: Date.now() - started.startedAt,
         outcome: event.outcome,
       });
@@ -123,12 +123,12 @@ export default defineInstrumentation({
     recordOutputs: false,
   }),
   events: {
-    "action.started": async (event) => {
+    "tool.call.started": async (event) => {
       await sendAuditRecord({
         id: event.idempotencyKey,
         input: redactApiKey(event.input),
         kind: event.kind,
-        name: event.name,
+        name: event.toolName,
       });
     },
   },
@@ -155,21 +155,22 @@ Prefer `recordInputs: false` or `recordOutputs: false` when the destination does
 start and its terminal event share an `idempotencyKey`; use it as a stable
 operation key when upserting records across replays.
 
-| Lifecycle        | Events                                                                                                            | Meaning                                                                                                                                                                          |
-| ---------------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Session          | `session.started`, `session.waiting`, `session.completed`, `session.failed`                                       | Track a session from creation through suspension or termination. `session.waiting` is resumable; `session.completed` and `session.failed` are terminal.                          |
-| Turn             | `turn.started`, `turn.completed`, `turn.cancelled`, `turn.failed`                                                 | Track one turn. Cancellation is not a failure and commonly leaves the session waiting for another turn.                                                                          |
-| Channel delivery | `channel.delivery.started`, `channel.delivery.completed`, `channel.delivery.cancelled`, `channel.delivery.failed` | Track an inbound channel delivery while eve processes its turn. These events are emitted when the channel provides delivery metadata.                                            |
-| Step attempt     | `step.attempt.started`, `step.attempt.completed`, `step.attempt.failed`, `step.attempt.metadata`                  | Track each model-step attempt; retries have separate attempts. `step.attempt.metadata` is emitted after a step only when the AI SDK supplies provider metadata.                  |
-| Model call       | `model.call.started`, `model.call.completed`, `model.call.failed`                                                 | Track an individual call to the model provider. Completion includes usage and finish reason; content fields follow the trace policy.                                             |
-| Action           | `action.started`, `action.completed`, `action.failed`                                                             | Track eve's durable dispatch of a tool, skill load, local subagent, or remote agent. A failed event's `outcome` distinguishes failure, rejection, cancellation, and abandonment. |
-| Tool call        | `tool.call.started`, `tool.call.completed`, `tool.call.failed`                                                    | Track the AI SDK's in-process tool execution boundary, including its input and result when allowed by the trace policy.                                                          |
-| User input       | `input.requested`, `input.resolved`                                                                               | Track a question, tool approval, or session-limit request and its resolution. The resolution includes an outcome such as `answered`, `approved`, `denied`, or `cancelled`.       |
-| Memory operation | `memory.operation.started`, `memory.operation.completed`, `memory.operation.failed`                               | Track a memory-store search or write. Events include the operation name, phase, and memory slot; completion may include a record count and records.                              |
-
-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.
-
-For local and remote subagents, `action.completed` and `action.failed` include the child turn's `usage` directly. Token counts are always present when the child reports usage; `usage.costUsd` is present only when the model provider reports a price. Without the action-level usage, consumers would have to correlate child model events through trace lineage and sum their provider metadata, which is harder to do reliably across retries and parked turns.
+| Lifecycle        | Events                                                                                                            | Meaning                                                                                                                                                                                |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Session          | `session.started`, `session.waiting`, `session.completed`, `session.failed`                                       | Track a session from creation through suspension or termination. `session.waiting` is resumable; `session.completed` and `session.failed` are terminal.                                |
+| Turn             | `turn.started`, `turn.completed`, `turn.cancelled`, `turn.failed`                                                 | Track one turn. Cancellation is not a failure and commonly leaves the session waiting for another turn.                                                                                |
+| Channel delivery | `channel.delivery.started`, `channel.delivery.completed`, `channel.delivery.cancelled`, `channel.delivery.failed` | Track an inbound channel delivery while eve processes its turn. These events are emitted when the channel provides delivery metadata.                                                  |
+| Step attempt     | `step.attempt.started`, `step.attempt.completed`, `step.attempt.failed`, `step.attempt.metadata`                  | Track each model-step attempt; retries have separate attempts. `step.attempt.metadata` is emitted after a step only when the AI SDK supplies provider metadata.                        |
+| Model call       | `model.call.started`, `model.call.completed`, `model.call.failed`                                                 | Track an individual call to the model provider. Completion includes usage and finish reason; content fields follow the trace policy.                                                   |
+| Tool call        | `tool.call.started`, `tool.call.completed`, `tool.call.failed`                                                    | Track a tool, skill load, local subagent, or remote-agent call through durable settlement. A failed event's `outcome` distinguishes failure, rejection, cancellation, and abandonment. |
+| User input       | `input.requested`, `input.resolved`                                                                               | Track a question, tool approval, or session-limit request and its resolution. The resolution includes an outcome such as `answered`, `approved`, `denied`, or `cancelled`.             |
+| Memory operation | `memory.operation.started`, `memory.operation.completed`, `memory.operation.failed`                               | Track a memory-store search or write. Events include the operation name, phase, and memory slot; completion may include a record count and records.                                    |
+
+Each call emits one `tool.call.*` lifecycle to authored providers. SDK execution callbacks do not emit a second lifecycle. Tool calls can remain open across approvals, parked turns, and worker replacement.
+
+For local and remote subagents, `tool.call.completed` and `tool.call.failed` include the child turn's `usage` directly. Token counts are always present when the child reports usage; `usage.costUsd` is present only when the model provider reports a price.
+
+When upgrading, replace `action.started`, `action.completed`, and `action.failed` handlers with their `tool.call.*` equivalents. Read `event.toolName` instead of `event.name` on start events. The OpenTelemetry trace schema remains version 4.
 
 Handlers from different files run concurrently and are failure-isolated. Do
 not depend on execution order. Use `flush` to drain buffered records and

package/docs/guides/instrumentation/otel.mdx

@@ -126,6 +126,10 @@ The resolver receives the channel, session, final model input, step, and turn.
 Keys beginning with `eve.` are reserved. Content excluded by
 `otel({ tracePolicy })` is not available to the resolver.
 
+Authored values appear under `ai.settings.context.*`. Framework channel, session,
+step, turn, and version identifiers use structural span attributes instead of
+runtime-context copies. `ai.settings.context.eve.environment` remains available.
+
 ## Trace topology
 
 OpenTelemetry destinations receive the following trace topology for an ordinary
@@ -135,8 +139,7 @@ agent turn:
 invoke_agent <agent>
   └── agent.step
         ├── chat <model>
-        └── agent.action
-              └── execute_tool <tool>
+        └── execute_tool <tool>
 ```
 
 Each root agent turn starts a new trace. If eve receives a local caller's trace
@@ -146,6 +149,14 @@ context, the first subagent turn starts a new trace. Later turns in the child
 session start new traces. They do not use the original dispatch span as their
 parent.
 
+Use `gen_ai.tool.call.id` to correlate tool and approval spans. Tool failures use
+`error.type`. These attributes replace the duplicate `agent.action.call_id` and
+`agent.action.error.code` fields without changing trace schema version 4.
+
+Model and activation spans record token counts under `gen_ai.usage.*`, without
+duplicate `agent.usage.*` token fields. Step and tool spans retain `agent.usage.*`.
+Cost values remain unchanged.
+
 A remote child starts a separate trace with a root `invoke_agent` span. Its first
 turn links to the caller with `eve.link.type=agent.dispatch`. The receiving
 deployment applies its sampler. Queries for local dispatches must use

package/docs/reference/cli.md

@@ -393,11 +393,11 @@ Span rows carry inline metrics when the span recorded them — `↑input`/`↓ou
 
 With local caller trace context, the first local subagent turn uses the caller's trace. Its span is a child of the dispatch span. A remote child starts a separate root trace and links its first turn to the dispatch with `eve.link.type=agent.dispatch`. Remote requests use W3C `tracestate` to identify that dispatch span if platform HTTP handling changes `traceparent`. Later child turns start new traces. All related sessions have the same `gen_ai.conversation.id`. `agent.subagent.name` identifies the subagent.
 
-Each workflow tool call has an `agent.action` span and an `execute_tool <tool>` span. The first turn of each local session it opens with `ctx.agent` is a child of the call's `agent.action` span. A remote session links to that action from its own trace. An individual `ctx.agent` call does not create a separate dispatch span. Only agent execution uses `invoke_agent`.
+Each workflow tool call has one `execute_tool <tool>` span. The first turn of each local session it opens with `ctx.agent` is a child of that tool span. A remote session links to the tool span from its own trace. An individual `ctx.agent` call does not create a separate dispatch span. Only agent execution uses `invoke_agent`.
 
 Outbound MCP `tools/call` requests add MCP semantic attributes to the matching `execute_tool` span. When eve has no tool span to enrich, it creates a `CLIENT` `tools/call <tool>` span. Each `tools/list` discovery also has a `CLIENT` span. Configured OpenTelemetry propagation fields are injected into MCP `params._meta` for JSON-RPC bodies up to 1 MiB and propagation metadata up to 8 KiB; larger requests are sent unchanged. eve removes its audience and session-lineage baggage before forwarding, and keeps the input/output content-capture policy local.
 
-`connection_execute` records the connector call as a child of its outer `agent.action` span, with `agent.action.parent_call_id` identifying the outer call. Both spans retain `agent.action.kind=tool-call`; consumers can distinguish nested calls by the parent call ID. The nested span's `gen_ai.tool.call.arguments` holds the validated connector input, including schema defaults, when input capture is enabled. Its duration covers the reporting of the nested result, not the connector request; use the outer call's `execute_tool` span for execution timing.
+`connection_execute` records the connector call as a child of its outer `execute_tool` span, with `agent.action.parent_call_id` identifying the outer call. Both spans retain `agent.action.kind=tool-call`; consumers can distinguish nested calls by the parent call ID. The nested span's `gen_ai.tool.call.arguments` holds the validated connector input, including schema defaults, when input capture is enabled. Its duration covers the reporting of the nested result, not the connector request; use the outer call's `execute_tool` span for execution timing.
 
 Each root agent turn starts a new trace. With local caller trace context, that trace includes the first turn of each local subagent it starts. Remote child turns and later local child turns start separate traces. If a worker is replaced, the new worker uses the prepared trace context for the same turn. Supply the conversation ID to show all related traces, oldest first.
 
@@ -426,7 +426,7 @@ eve link
 eve link --non-interactive --project <name-or-id> [--team <team-id-or-slug>]
 ```
 
-Links the current directory to a Vercel project. After selecting a team, you can create a project named for the agent or link an existing project. The existing-project picker shows recent projects; type a project name and choose **Search for '<name>'** to search the rest of that team's projects. Vercel links the resolved project, eve verifies its project ID, and then pulls the project's environment so an AI Gateway credential (`VERCEL_OIDC_TOKEN` or `AI_GATEWAY_API_KEY`) lands in `.env.local`. Running it again re-links: the pickers always run, and the new choice wins.
+Links the current directory to a Vercel project. After selecting a team, you can create a project named for the agent or link an existing project. The existing-project picker shows recent projects; type a project name and choose **Search for `'<name>'`** to search the rest of that team's projects. Vercel links the resolved project, eve verifies its project ID, and then pulls the project's environment so an AI Gateway credential (`VERCEL_OIDC_TOKEN` or `AI_GATEWAY_API_KEY`) lands in `.env.local`. Running it again re-links: the pickers always run, and the new choice wins.
 
 For CI or an agent, pass `--non-interactive` and `--project`. `--project` accepts the same Vercel project name or ID as `vercel link`; `--team` accepts its team ID or slug. The command never opens a picker or browser in this mode. A running `eve dev` reloads env files automatically, so you don't need to restart after the pull.
 

package/docs/reference/typescript-api.md

@@ -61,6 +61,8 @@ Tool-wide authoring helpers and types such as `defineTool`, `defineWorkflowTool`
 
 `AgentReasoningDefinition` is exported from `eve` for the top-level `defineAgent({ reasoning })` setting. `AgentLimitsDefinition` is exported for `defineAgent({ limits })`. `AgentWorkflowDefinition`, `AgentWorkflowRetentionDefinition`, and `AgentWorkflowWorldDefinition` are exported from `eve` for the `defineAgent({ experimental: { workflow } })` config shape. `WebSearchToolInput` and `WebSearchProvider` are exported from `eve/tools/web_search`.
 
+`webSearch({ provider })` selects `"exa"`, `"parallel"`, or `"browserbase"` for AI Gateway search using the Gateway model's credentials. Direct provider models keep their native search implementation when supported. See [Built-in tools](../concepts/built-in-tools#web_search) for setup and provider behavior.
+
 `defineInstructions` accepts `{ content: string, role?: "system" | "user" }`; omitted `role` means `"system"`. Its `eve/instructions` version of `defineDynamic` accepts only `session.started` and `turn.started` handlers returning `defineInstructions(...)` or `null`. The legacy `{ markdown: string }` definition remains available as a deprecated system-role form.
 
 The `eve/connections` version of `defineDynamic` accepts `session.started` and
@@ -141,10 +143,10 @@ Tool definitions accept `availableInSubagents: false` to restrict the tool to to
 | `eve/instrumentation`                                                             | `defineInstrumentation`, `disableInstrumentation`, `isChannel`, lifecycle provider types                                       |
 | `eve/instrumentation/otel`                                                        | `otel`, `otelIntegration`, `localTraces`, `agentRuns`, OpenTelemetry policy types                                              |
 | `eve/local-dev`                                                                   | `getLocalDevCapability`, `LocalDevCapability`                                                                                  |
-| [`eve/models`](../guides/evaluate)                                                | Automatic model selection with `auto`                                                                                          |
+| [`eve/models`](../guides/decide)                                                  | Automatic model selection with `auto`                                                                                          |
 | `eve/models/openai`                                                               | `openai`, `chatgpt`, deprecated `experimental_chatgpt`                                                                         |
 | `eve/models/anthropic`                                                            | `anthropic`                                                                                                                    |
-| [`eve/ai`](../guides/evaluate#evaluate-inside-a-tool)                             | Standalone `evaluate`                                                                                                          |
+| [`eve/ai`](../guides/decide#decide-inside-a-tool)                                 | Standalone `decide`                                                                                                            |
 | `eve/evals`                                                                       | `defineEval`, `defineEvalConfig`, `mockModel`, eval types                                                                      |
 | `eve/evals/expect`                                                                | `includes`, `equals`, `matches`, `similarity`                                                                                  |
 | `eve/evals/reporters`                                                             | `Braintrust`, `JUnit`, `EvalReporter`                                                                                          |

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

@@ -37,17 +37,17 @@ export default defineTool({
 | `never()`  | Never require approval (the default when omitted).                                 |
 | `once()`   | Require approval only the first time the tool runs in a session; auto-allow after. |
 | `always()` | Require approval before every call.                                                |
-| `auto()`   | Ask an evaluation model whether to run the exact call or require user approval.    |
+| `auto()`   | Ask a decision model whether to run the exact call or require user approval.       |
 
 By default, omitted `approval` behaves like `never()`, so tool calls may execute without human approval. Require human approval or other safeguards for sensitive, irreversible, regulated, financial, healthcare, employment, housing, legal, safety-impacting, user-impacting, or external side-effecting actions.
 
-`auto()` uses an [AI SDK evaluation model](/docs/guides/evaluate) to classify each call as `clear` or `caution`. It defaults to `typesafe-ai/jev`, TypeSafe AI's [Jev evaluation model](https://vercel.com/i/what-is-jev). Like `evaluate`, a model string uses Vercel AI Gateway unless the application configures a global AI SDK default provider:
+`auto()` uses an [AI SDK decision model](/docs/guides/decide) to classify each call as `clear` or `caution`. It defaults to `typesafe-ai/jev`, TypeSafe AI's [Jev decision model](https://vercel.com/i/what-is-jev). Like `decide`, a model string uses Vercel AI Gateway unless the application configures a global AI SDK default provider:
 
 ```ts
 approval: auto({ model: "typesafe-ai/jev" });
 ```
 
-The evaluation model reviews the tool name and input for dangerous effects. A caution, failed review, or incomplete input requires user approval. The tool input is sent to the evaluation model's provider.
+The decision model reviews the tool name and input for dangerous effects. A caution, failed review, or incomplete input requires user approval. The tool input is sent to the decision model's provider.
 
 Override the classifier text for application-specific policy:
 
@@ -84,7 +84,9 @@ Gating a side effect on approval is also how you make non-idempotent work safe a
 
 ### Authorizing approval responses
 
-You may also define an approval response policy that decides whether the authenticated person who selects **Approve** or **Cancel** may settle that specific call:
+By default, only the person whose turn requested a call can approve or cancel it.
+
+Define an approval response policy to change who may settle a call, for example, to specify a set of designated approvers who must approve a certain tool. A tool with a `response` policy replaces the default entirely, so return `{ status: "allowed" }` to let any responder through:
 
 ```ts title="agent/tools/refund_charge.ts"
 import { defineTool } from "eve/tools";

package/docs/tools/workflows.mdx

@@ -588,7 +588,7 @@ export default defineAgent({
 Define the model-visible router under `agent/tools/`. Build the Jev criteria from the subagents' effective descriptions, then pass its typed choice directly to `ctx.agent()`:
 
 ```ts title="agent/tools/agent-router.ts"
-import { evaluate } from "eve/ai";
+import { decide } from "eve/ai";
 import { defineWorkflowTool } from "eve/tools";
 import { z } from "zod";
 
@@ -599,7 +599,7 @@ async function chooseTarget(
 ) {
   "use step";
 
-  const result = await evaluate({
+  const result = await decide({
     abortSignal,
     state: { task },
     questions: {
@@ -637,7 +637,7 @@ export default defineWorkflowTool({
 });
 ```
 
-The evaluation runs in a step so workflow replay records its result instead of making the routing request again. The parent model receives `agent-router`, but not `researcher` or `operator`. Jev returns the typed `"researcher" | "operator"` choice, and the selected subagent's reply becomes the `agent-router` tool result.
+The decision runs in a step so workflow replay records its result instead of making the routing request again. The parent model receives `agent-router`, but not `researcher` or `operator`. Jev returns the typed `"researcher" | "operator"` choice, and the selected subagent's reply becomes the `agent-router` tool result.
 
 `ctx.agents` is a replay-stable metadata snapshot taken when the session admits the call. In a `serve` task, it follows the call being served. In a top-level root workflow, `ctx.agents.agent` always represents the root-copy target and carries the root's authored `description` when provided. The snapshot also includes declared agents hidden from the parent model with `tool: false` or `disableTool()`, but exposes no model definitions, credentials, or callbacks. A delegated root copy omits `agent`, so `agentRouter()` cannot select another root copy recursively. Invocation still checks each target's availability through `ctx.agent()`.
 
@@ -651,7 +651,7 @@ import { agentRouter } from "eve/tools/agent-router";
 export default agentRouter();
 ```
 
-Its input is `{ message: string }`. `agentRouter()` ignores entries without a non-empty description. With two or more described targets, it sends the message and effective descriptions to Jev, then sends the message to a new session with the selected agent through `ctx.agent()` and returns its reply. It invokes a sole target without evaluation. Each call
+Its input is `{ message: string }`. `agentRouter()` ignores entries without a non-empty description. With two or more described targets, it sends the message and effective descriptions to Jev, then sends the message to a new session with the selected agent through `ctx.agent()` and returns its reply. It invokes a sole target without decision. Each call
 runs as a [task](#run-calls-as-tasks-task), so the reply reaches the model as the task's result. In a top-level root session, the candidates include the root-copy `agent`; delegated root copies and declared subagent contexts include only their declared targets.
 
 When an authored tool accepts a JSON Schema supplied by the model, represent that input with a permissive object such as `z.looseObject({})`. Avoid `z.record(z.string(), z.json())`: its generated JSON Schema uses `propertyNames`, which OpenAI does not support. Validate the supplied value at the point where your tool consumes it.