eve 0.13.7 → 0.14.0

package/dist/src/shared/agent-definition.d.ts

@@ -1,4 +1,4 @@
-import type { LanguageModel } from "ai";
+import type { CallSettings, LanguageModel } from "ai";
 import type { StandardJSONSchemaV1 } from "#compiled/@standard-schema/spec/index.js";
 import type { JsonObject } from "#shared/json.js";
 import type { ModuleSourceRef } from "#shared/source-ref.js";
@@ -9,6 +9,10 @@ import type { ModuleSourceRef } from "#shared/source-ref.js";
 export interface AgentModelOptionsDefinition {
     readonly providerOptions?: Record<string, JsonObject>;
 }
+/**
+ * Provider-agnostic reasoning effort forwarded to the AI SDK model call.
+ */
+export type AgentReasoningDefinition = NonNullable<CallSettings["reasoning"]>;
 /**
  * How an agent's model is reached at runtime, decided at compile time from the
  * authored model value.
@@ -93,20 +97,8 @@ export interface PublicAgentCompactionDefinition {
  * Experimental, opt-in agent capabilities authored in `agent.ts`.
  *
  * These options are unstable and may change or be removed in any release.
- * Each agent (the root agent and every subagent) carries its own flags, so
- * code mode can be enabled for the whole graph, only a subagent, or only
- * the parent.
  */
 export interface AgentExperimentalDefinition {
-    /**
-     * Routes executable tools through a sandboxed code-execution wrapper
-     * instead of exposing them directly to the model. The model writes
-     * JavaScript that calls the tools inside the sandbox.
-     *
-     * When unset, eve falls back to the `EVE_EXPERIMENTAL_CODE_MODE`
-     * environment variable (`"1"` enables it) for backwards compatibility.
-     */
-    readonly codeMode?: boolean;
     /**
      * Durable Workflow runtime configuration. Root agents may use this to select
      * the Workflow world backing sessions and runs.
@@ -161,6 +153,7 @@ export type InternalAgentDefinition = {
     experimental?: AgentExperimentalDefinition;
     model: InternalAgentModelDefinition;
     outputSchema?: JsonObject;
+    reasoning?: AgentReasoningDefinition;
     source?: ModuleSourceRef;
 };
 /**
@@ -199,6 +192,11 @@ export type PublicAgentDefinition = {
      */
     readonly modelContextWindowTokens?: number;
     readonly modelOptions?: AgentModelOptionsDefinition;
+    /**
+     * Provider-agnostic reasoning effort for the agent's turn model calls.
+     * Support for individual levels depends on the selected model and provider.
+     */
+    readonly reasoning?: AgentReasoningDefinition;
     /**
      * Optional structured return type used when this agent runs in task mode
      * (for example as a subagent, schedule, or remote job). Interactive

package/dist/src/shared/dynamic-tool-definition.d.ts

@@ -1,7 +1,7 @@
 import type { ModelMessage } from "ai";
 import type { PublicToolInputSchema, PublicToolOutputSchema, ToolModelOutput } from "#shared/tool-definition.js";
 import type { SessionContext } from "#public/definitions/callback-context.js";
-import type { NeedsApprovalContext } from "#public/definitions/tool.js";
+import type { Approval } from "#public/definitions/approval.js";
 import type { SessionAuth } from "#context/keys.js";
 import type { HandleMessageStreamEvent } from "#protocol/message.js";
 type ToolContext = SessionContext;
@@ -64,13 +64,13 @@ export interface DynamicToolEntry<TInput = Record<string, unknown>, TOutput = an
     readonly toModelOutput?: (output: TOutput) => ToolModelOutput | Promise<ToolModelOutput>;
     /**
      * Optional per-call approval gate, mirroring the authored-tool
-     * `needsApproval` contract: return `true` to require user approval
+     * `approval` contract: return `"user-approval"` to require user approval
      * before the call executes. Only honored for step-scoped dynamic
      * tools, whose live `execute` closures survive into the harness;
      * session/turn-scoped tools replay from durable metadata and cannot
      * carry a function across replay.
      */
-    readonly needsApproval?: (ctx: NeedsApprovalContext) => boolean;
+    readonly approval?: Approval;
 }
 /**
  * A resolved tool set: keys are entry identifiers, values are

package/dist/src/shared/tool-definition.d.ts

@@ -32,8 +32,7 @@ export interface PublicToolDefinition<TInput = unknown, TOutput = unknown> exten
     inputSchema: PublicToolInputSchema<TInput>;
     /**
      * Optional schema describing the value returned by the tool executor.
-     * Code mode uses this to expose typed host-tool return values to the
-     * generated program, and the AI SDK can use it for tool result typing.
+     * The AI SDK can use this for tool result typing.
      */
     outputSchema?: PublicToolOutputSchema<TOutput>;
 }

package/dist/src/shared/workflow-sandbox.d.ts

@@ -0,0 +1,37 @@
+import type { ToolSet } from "ai";
+import type * as CodeModeModule from "#compiled/experimental-ai-sdk-code-mode/index.js";
+/** Model-facing tool name for eve's dynamic subagent orchestration tool. */
+export declare const WORKFLOW_TOOL_NAME = "Workflow";
+type WorkflowSandboxModule = Pick<typeof CodeModeModule, "continueCodeModeInterrupt" | "createCodeModeTool" | "getCodeModeInterrupt" | "requestCodeModeInterrupt" | "unwrapCodeModeResult">;
+export type WorkflowSandboxInterrupt = CodeModeModule.CodeModeInterrupt;
+export type WorkflowSandboxLifecycle = NonNullable<CodeModeModule.CodeModeOptions["lifecycle"]>;
+export type WorkflowSandboxContinuationSecurity = CodeModeModule.CodeModeContinuationSecurityOptions;
+export declare function installWorkflowSandboxModule(module: WorkflowSandboxModule): void;
+export declare function createWorkflowSandboxTool(input: {
+    readonly continuationSecurity: WorkflowSandboxContinuationSecurity;
+    readonly hostTools: ToolSet;
+    readonly lifecycle?: WorkflowSandboxLifecycle;
+}): Promise<ToolSet[string]>;
+export declare function requestWorkflowSandboxInterrupt(input: {
+    readonly kind: string;
+    readonly runtimeAction: unknown;
+    readonly toolInput: unknown;
+    readonly toolName: string;
+}): Promise<unknown>;
+export declare function getWorkflowSandboxInterrupt(result: unknown, continuationSecurity: WorkflowSandboxContinuationSecurity): Promise<WorkflowSandboxInterrupt | undefined>;
+export declare function continueWorkflowSandboxInterrupt(input: {
+    readonly continuationSecurity: WorkflowSandboxContinuationSecurity;
+    readonly interrupt: WorkflowSandboxInterrupt;
+    readonly lifecycle?: WorkflowSandboxLifecycle;
+    readonly resolution: unknown;
+    readonly tools: ToolSet;
+}): Promise<unknown>;
+export declare function unwrapWorkflowSandboxResult(value: unknown, continuationSecurity: WorkflowSandboxContinuationSecurity): Promise<{
+    readonly output: unknown;
+    readonly status: "completed";
+} | {
+    readonly interrupt: WorkflowSandboxInterrupt;
+    readonly status: "interrupted";
+}>;
+export declare function readWorkflowSandboxResolution(options: unknown): unknown;
+export {};

package/dist/src/shared/workflow-sandbox.js

@@ -0,0 +1 @@
+const WORKFLOW_TOOL_NAME=`Workflow`,WORKFLOW_SANDBOX_MODULE_KEY=Symbol.for(`eve.workflowSandbox.module`),WORKFLOW_SANDBOX_MODULE_SPECIFIER=[`#compiled`,`experimental-ai-sdk-code-mode`,`index.js`].join(`/`);let workflowSandboxModulePromise;function installWorkflowSandboxModule(e){globalThis[WORKFLOW_SANDBOX_MODULE_KEY]=e}async function createWorkflowSandboxTool(e){let{createCodeModeTool:t}=await loadWorkflowSandboxModule();return t(e.hostTools,createWorkflowSandboxOptions(e.continuationSecurity,e.lifecycle))}async function requestWorkflowSandboxInterrupt(e){let{requestCodeModeInterrupt:t}=await loadWorkflowSandboxModule();return t(e)}async function getWorkflowSandboxInterrupt(e,t){let{getCodeModeInterrupt:n}=await loadWorkflowSandboxModule();return n(e,t)}async function continueWorkflowSandboxInterrupt(e){let{continueCodeModeInterrupt:t}=await loadWorkflowSandboxModule();return t({interrupt:e.interrupt,options:createWorkflowSandboxOptions(e.continuationSecurity,e.lifecycle),resolution:e.resolution,tools:e.tools})}async function unwrapWorkflowSandboxResult(e,t){let{unwrapCodeModeResult:n}=await loadWorkflowSandboxModule();return n(e,t)}function readWorkflowSandboxResolution(e){if(typeof e!=`object`||!e)return;let t=e.codeModeInterrupt;if(!(typeof t!=`object`||!t))return t.resolution}function createWorkflowSandboxOptions(e,t){let n={continuationSecurity:e};return t!==void 0&&(n.lifecycle=t),n}async function loadWorkflowSandboxModule(){let e=globalThis[WORKFLOW_SANDBOX_MODULE_KEY];return e===void 0?(workflowSandboxModulePromise??=importWorkflowSandboxModule(WORKFLOW_SANDBOX_MODULE_SPECIFIER),await workflowSandboxModulePromise):e}async function importWorkflowSandboxModule(e){return await import(e)}export{WORKFLOW_TOOL_NAME,continueWorkflowSandboxInterrupt,createWorkflowSandboxTool,getWorkflowSandboxInterrupt,installWorkflowSandboxModule,readWorkflowSandboxResolution,requestWorkflowSandboxInterrupt,unwrapWorkflowSandboxResult};

package/docs/agent-config.md

@@ -1,6 +1,6 @@
 ---
 title: "agent.ts"
-description: "Set the agent's runtime config in agent.ts with defineAgent, including the model and compaction."
+description: "Set the agent's runtime config in agent.ts with defineAgent, including the model, reasoning effort, and compaction."
 ---
 
 An agent's `agent.ts` calls `defineAgent` (from `eve`) to set its runtime config.
@@ -33,12 +33,33 @@ import { anthropic } from "@ai-sdk/anthropic";
 import { defineAgent } from "eve";
 
 export default defineAgent({
-  model: anthropic("claude-opus-4.8"),
+  model: anthropic("claude-opus-4-8"),
 });
 ```
 
+Direct provider model ids use the provider's native format. For Anthropic, the
+version uses hyphens (`claude-opus-4-8`), while the Gateway id above uses a dot
+(`anthropic/claude-opus-4.8`).
+
 Model use is subject to the terms, data-processing commitments, retention behavior, and available controls of the selected provider and routing path. Review the [AI Gateway model catalog](https://vercel.com/ai-gateway/models) for gateway-routed models, and review the provider's terms when you configure a direct `LanguageModel`.
 
+## Reasoning effort
+
+Set `reasoning` to control the model's reasoning effort through AI SDK's
+provider-agnostic option:
+
+```ts title="agent/agent.ts"
+export default defineAgent({
+  model: "openai/gpt-5.5",
+  reasoning: "high",
+});
+```
+
+Supported values are `"provider-default"`, `"none"`, `"minimal"`, `"low"`,
+`"medium"`, `"high"`, and `"xhigh"`. The selected model and provider determine
+which levels are available and how they map to provider-native settings. Use
+`modelOptions.providerOptions` when you need provider-specific reasoning controls.
+
 ## Compaction
 
 Compaction summarizes older turns as you approach the context window. It's on by default, so you only tune when it kicks in. Lower `thresholdPercent` to compact sooner:
@@ -85,14 +106,13 @@ external in hosted output, list it in `build.externalDependencies`.
 
 `defineAgent` takes a few more fields, all optional. For the exported types, see the [TypeScript API](./reference/typescript-api).
 
-| Field          | Type                                                    | Default     | Description                                                                                                                                                                                                                                                                                                                                                                       |
-| -------------- | ------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `modelOptions` | `AgentModelOptionsDefinition`                           | none        | Provider option overrides forwarded to the model call.                                                                                                                                                                                                                                                                                                                            |
-| `experimental` | `{ codeMode?: boolean; workflow?: { world?: string } }` | flags unset | Opt-in flags that can change or disappear in any release. Treat them as unstable. `codeMode` routes executable tools through a sandboxed code-execution wrapper, where the model writes JavaScript that calls the tools inside the [sandbox](./sandbox). `workflow.world` selects the Workflow world package backing session state, queues, hooks, and streams on the root agent. |
-| `outputSchema` | Standard Schema or a JSON Schema object                 | none        | Structured return type for task-mode runs (a subagent, schedule, or remote job). Interactive conversation turns ignore it unless the client supplies a per-message schema.                                                                                                                                                                                                        |
-| `build`        | `{ externalDependencies?: string[] }`                   | none        | Hosted-build packaging controls. `externalDependencies` keeps listed packages external while eve compiles authored modules such as tools and channels, and traces those packages into the hosted output.                                                                                                                                                                          |
-
-`codeMode` is experimental and may change or be removed.
+| Field          | Type                                    | Default          | Description                                                                                                                                                                                                   |
+| -------------- | --------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `reasoning`    | `AgentReasoningDefinition`              | provider default | Provider-agnostic reasoning effort forwarded to the agent's turn model calls.                                                                                                                                 |
+| `modelOptions` | `AgentModelOptionsDefinition`           | none             | Provider option overrides forwarded to the model call.                                                                                                                                                        |
+| `experimental` | `{ workflow?: { world?: string } }`     | unset            | Opt-in settings that can change or disappear in any release. Treat them as unstable. `workflow.world` selects the Workflow world package backing session state, queues, hooks, and streams on the root agent. |
+| `outputSchema` | Standard Schema or a JSON Schema object | none             | Structured return type for task-mode runs (a subagent, schedule, or remote job). Interactive conversation turns ignore it unless the client supplies a per-message schema.                                    |
+| `build`        | `{ externalDependencies?: string[] }`   | none             | Hosted-build packaging controls. `externalDependencies` keeps listed packages external while eve compiles authored modules such as tools and channels, and traces those packages into the hosted output.      |
 
 `externalDependencies` is a packaging control only. It keeps selected packages as runtime dependencies in the hosted output; it does not authorize, configure, or review any third-party service those packages may call.
 

package/docs/channels/custom.mdx

@@ -46,7 +46,7 @@ export default defineChannel({
 
 Declare routes with the `POST()` and `GET()` helpers. Each route handler receives the raw `Request` and a helpers object:
 
-- `send(message, { auth, continuationToken, state? })` starts or resumes a session. Returns a `Session`.
+- `send(message, { auth, continuationToken, state?, title? })` starts or resumes a session. `title` overrides the new workflow session's display title without changing the model message. Returns a `Session`.
 - `getSession(sessionId)` looks up an existing session. The returned `Session` exposes `getEventStream({ startIndex? })` for streaming.
 - `receive(channel, ...)` hands inbound work to a different channel for cross-channel hand-off.
 - `params` holds route parameters extracted from the path pattern.
@@ -182,7 +182,7 @@ When a parent agent dispatches a subagent, the framework forwards the parent's c
 
 ## Continuation tokens
 
-Each call to `send(message, { auth, continuationToken, state? })` from a channel route addresses a session by its channel-local raw token. The framework prepends the channel name, derived from the file stem under `agent/channels/`, before handing the token to the runtime.
+Each call to `send(message, { auth, continuationToken, state?, title? })` from a channel route addresses a session by its channel-local raw token. The framework prepends the channel name, derived from the file stem under `agent/channels/`, before handing the token to the runtime.
 
 ```ts
 import { slackContinuationToken } from "eve/channels/slack";

package/docs/channels/slack.mdx

@@ -54,28 +54,22 @@ Inbound hooks decide whether to dispatch a turn and with what `auth`. Return `{
 - `onDirectMessage(ctx, message)` handles `message.im` events (needs `im:history` scope). Bot-authored messages and edits are filtered out first.
 - `onInteraction(action, ctx)` handles `block_actions` callbacks not consumed by HITL.
 
-You get the triggering mention by default, but not the earlier replies in the thread. Pull them in with `loadThreadContextMessages` and return them as `context`, which eve appends to history as user messages the model sees on every later turn. Use `since: "last-agent-reply"` so repeated mentions in one thread inject only what is new:
+eve attaches the triggering Slack user id to the same model message as the message text. This keeps speaker attribution intact when several people use one thread without making profile lookup requests.
+
+You get the triggering mention by default, but not the earlier replies in the thread. Enable `threadContext` to fetch and inject them with every message attributed by stable Slack user id. Use `since: "last-agent-reply"` so repeated mentions inject only what is new:
 
 ```ts
-import { defaultSlackAuth, loadThreadContextMessages, slackChannel } from "eve/channels/slack";
+import { slackChannel } from "eve/channels/slack";
 import { connectSlackCredentials } from "@vercel/connect/eve";
 
 export default slackChannel({
   credentials: connectSlackCredentials("slack/my-agent"),
-  async onAppMention(ctx, message) {
-    const auth = defaultSlackAuth(message, ctx);
-    const prior = await loadThreadContextMessages(ctx.thread, message, {
-      since: "last-agent-reply",
-    });
-    if (prior.length === 0) return { auth };
-    const transcript = prior
-      .map((m) => `${m.isMe ? "you" : (m.user ?? "user")}: ${m.markdown}`)
-      .join("\n");
-    return { auth, context: [`Recent thread messages since your last reply:\n\n${transcript}`] };
-  },
+  threadContext: { since: "last-agent-reply" },
 });
 ```
 
+`threadContext` performs one `conversations.replies` request for each triggering thread reply and requires the matching Slack history scope. Omit it when the agent should see only direct mentions. `loadThreadContextMessages` remains available when you need custom filtering or non-model processing of the raw thread messages.
+
 ### Delivery
 
 The default handlers reply in-thread and show progress. Typing indicators post automatically: `Thinking…` on inbound, `Working…` on `turn.started`, a truncated reasoning snippet on `reasoning.appended`, and tool status on `actions.requested`. Reasoning snippets build progressively: extensions of at least four characters appear immediately, while smaller streamed deltas use the five-second refresh interval to avoid one Slack request per token. Override `events["reasoning.appended"]` if you prefer generic wording. Override `onAppMention` or the `events` handlers to customize.

package/docs/connections/mcp.mdx

@@ -48,8 +48,8 @@ Use `allow` for the smallest safe surface, especially on MCP servers that expose
 
 MCP connections support the shared connection options:
 
-- `auth` for static tokens, Vercel Connect, or self-hosted interactive OAuth.
-- `headers` for API-key schemes or extra server configuration.
+- `auth` for static tokens, Vercel Connect, self-hosted interactive OAuth, or a per-caller provider resolver.
+- `headers` for static or per-caller API-key schemes and extra server configuration.
 - `approval` for human-in-the-loop gates before connection tools run.
 
 See [Connections](/docs/connections) for the shared auth, headers, and approval shapes.

package/docs/connections/openapi.mdx

@@ -34,6 +34,41 @@ OpenAPI connections use the shared connection fields from [Connections](/docs/co
 
 Use `baseUrl` when the spec's `servers` list is absent, points at the wrong environment, or needs to be pinned for this agent.
 
+## Path parameters
+
+When an operation path contains dynamic segments, declare each segment as an OpenAPI path parameter. eve exposes path, query, header, and cookie parameters as top-level tool inputs, then substitutes `in: "path"` values into the matching `{name}` placeholder before making the request.
+
+```ts title="agent/connections/cart.ts"
+import { defineOpenAPIConnection } from "eve/connections";
+
+export default defineOpenAPIConnection({
+  baseUrl: "https://api.example.com",
+  description: "Cart and checkout API.",
+  spec: {
+    openapi: "3.0.3",
+    info: { title: "Cart API", version: "1.0.0" },
+    paths: {
+      "/api/{dynamicsegment}/somethingelse": {
+        get: {
+          operationId: "getSomethingElse",
+          parameters: [
+            {
+              name: "dynamicsegment",
+              in: "path",
+              required: true,
+              schema: { type: "string" },
+            },
+          ],
+          responses: { "200": { description: "OK" } },
+        },
+      },
+    },
+  },
+});
+```
+
+The parameter `name` must exactly match the placeholder inside the path. If the spec omits the `in: "path"` parameter, the generated tool has no input for that segment and eve cannot fill it in from query parameters.
+
 ## Operation filters
 
 To narrow which generated tools the model sees, set exactly one of `operations.allow` or `operations.block`:
@@ -55,8 +90,8 @@ Filters match `operationId`. If an operation does not declare one, use the deter
 
 OpenAPI connections support the shared connection options:
 
-- `auth` for static tokens, Vercel Connect, or self-hosted interactive OAuth.
-- `headers` for API-key schemes or extra server configuration.
+- `auth` for static tokens, Vercel Connect, self-hosted interactive OAuth, or a per-caller provider resolver.
+- `headers` for static or per-caller API-key schemes and extra server configuration.
 - `approval` for human-in-the-loop gates before generated operation tools run.
 
 See [Connections](/docs/connections) for the shared auth, headers, and approval shapes.

package/docs/connections/overview.mdx

@@ -57,6 +57,38 @@ export default defineMcpClientConnection({
 });
 ```
 
+## Per-caller auth and headers
+
+When credentials or routing depend on the caller, make `auth` or `headers` a function. eve calls it inside the active turn and passes the same session context exposed to tools and hooks:
+
+```ts title="agent/connections/warehouse.ts"
+import { defineOpenAPIConnection } from "eve/connections";
+
+export default defineOpenAPIConnection({
+  spec: "https://warehouse.example.com/openapi.json",
+  description: "The caller's tenant-scoped warehouse.",
+  auth: (ctx) => ({
+    principalType: "user",
+    getToken: async () => ({
+      token: await tenantToken(ctx.session.auth.current),
+    }),
+  }),
+  headers: (ctx) => ({
+    "X-Tenant-Id": tenantId(ctx.session.auth.current),
+  }),
+});
+```
+
+An `auth` resolver returns the same provider object accepted by static `auth`, including a `connect(...)` provider for interactive OAuth. The resolver itself can be async. Header callbacks can return the whole map, as above, or resolve individual values:
+
+```ts
+headers: {
+  "X-Tenant-Id": (ctx) => tenantId(ctx.session.auth.current),
+}
+```
+
+Use `principalType: "user"` for per-user tokens so eve rejects unauthenticated callers and keys its step-local token cache by user. The resolver supplements route auth; it does not authenticate the inbound request. Static auth objects and header maps remain available when every caller shares the same configuration.
+
 ## Per-connection approval
 
 To put every tool a connection serves behind a human, use the helpers from `eve/tools/approval`:

package/docs/guides/deployment.md

@@ -74,11 +74,11 @@ import { anthropic } from "@ai-sdk/anthropic";
 import { defineAgent } from "eve";
 
 export default defineAgent({
-  model: anthropic("claude-opus-4.8"),
+  model: anthropic("claude-opus-4-8"),
 });
 ```
 
-With that shape, the model call goes directly to Anthropic and the runtime reads `ANTHROPIC_API_KEY`. The same pattern works for OpenAI after installing `@ai-sdk/openai`, using `openai("...")`, and setting `OPENAI_API_KEY`. This is the usual choice when self-deploying without any Vercel-managed services.
+With that shape, the model call goes directly to Anthropic and the runtime reads `ANTHROPIC_API_KEY`. Direct Anthropic model ids use hyphens (`claude-opus-4-8`), unlike the dotted Gateway id (`anthropic/claude-opus-4.8`). The same pattern works for OpenAI after installing `@ai-sdk/openai`, using `openai("...")`, and setting `OPENAI_API_KEY`. This is the usual choice when self-deploying without any Vercel-managed services.
 
 ## 4. Sandbox backend
 

package/docs/guides/dynamic-workflows.md

@@ -3,7 +3,7 @@ title: "Dynamic Workflows"
 description: "The experimental Workflow tool: let the model orchestrate its own subagents from model-authored JavaScript as one durable step."
 ---
 
-The experimental `Workflow` tool lets the model write JavaScript that coordinates the agent's own subagents as a single durable step. The program can run them in sequence, feed one result into the next, fan out over a list, and combine the results. You enable the capability and the model decides and runs the orchestration. It is the agents-only slice of [code mode](../agent-config#other-defineagent-fields) (the broader `codeMode` flag that routes all of an agent's tools through model-authored JavaScript).
+The experimental `Workflow` tool lets the model write JavaScript that coordinates the agent's own subagents as a single durable step. The program can run them in sequence, feed one result into the next, fan out over a list, and combine the results. You enable the capability and the model decides and runs the orchestration.
 
 A single turn can already call several subagents, and parallel tool calls dispatch concurrently. What a workflow adds is _programmatic_ coordination. The program decides how many subagents to run based on an earlier result, which output feeds which call, and how to combine everything. That is logic the model cannot express as a few one-off calls.
 
@@ -63,12 +63,6 @@ That is an allowlist, not a denylist. The sandbox cannot read files, open a sock
 - **Approval-safe.** A subagent that needs human approval (HITL, human-in-the-loop) mid-run surfaces its request to the user, and the workflow picks back up once that is answered, same as direct delegation.
 - **Observable.** Every orchestrated subagent emits the usual `subagent.called` / `subagent.completed` events on the parent stream and gets its own child session and stream. The telemetry matches direct delegation, so existing dashboards and cost attribution keep working.
 
-## Relationship to code mode
-
-[Code mode](../agent-config#other-defineagent-fields) is the broader version, where the model drives _all_ of an agent's tools (files, shell, web, and agents) from JavaScript. A workflow covers only the subagents. The two do not interfere. Enabling the `Workflow` tool leaves code mode untouched, and an agent can run both at once.
-
-`codeMode` is experimental and may change or be removed.
-
 ## What to read next
 
 - Declare the subagents a workflow orchestrates → [Subagents](../subagents)

package/docs/guides/frontend/overview.mdx

@@ -100,7 +100,7 @@ Assistant text, reasoning, tool calls, and tool results stream into `data` as th
 
 ## Human-in-the-loop prompts
 
-Tools opt into approval with `needsApproval`, and the model can also ask a question with `ask_question` — see [Human-in-the-loop](/docs/human-in-the-loop) for the server-side model. Either way the stream emits an `input.requested` event, and the pending request rides on a `dynamic-tool` part of the latest message at `part.toolMetadata?.eve?.inputRequest`. Read it, then answer through the same session with `send()`:
+Tools opt into approval with `approval`, and the model can also ask a question with `ask_question` — see [Human-in-the-loop](/docs/human-in-the-loop) for the server-side model. Either way the stream emits an `input.requested` event, and the pending request rides on a `dynamic-tool` part of the latest message at `part.toolMetadata?.eve?.inputRequest`. Read it, then answer through the same session with `send()`:
 
 ```tsx
 const request = agent.data.messages

package/docs/guides/frontend/use-eve-agent-svelte.mdx

@@ -78,7 +78,7 @@ await agent.send({
 
 ## Human-in-the-loop prompts
 
-A tool opts into approval with `needsApproval` ([Tools](../../tools)). When one fires, the pending request rides along on a `dynamic-tool` part of the latest message at `part.toolMetadata?.eve?.inputRequest`. Read it, then answer through the same session with `agent.send({ inputResponses })`:
+A tool opts into approval with `approval` ([Tools](../../tools)). When one fires, the pending request rides along on a `dynamic-tool` part of the latest message at `part.toolMetadata?.eve?.inputRequest`. Read it, then answer through the same session with `agent.send({ inputResponses })`:
 
 ```ts
 import type { EveDynamicToolPart, EveMessagePart } from "eve/svelte";

package/docs/guides/frontend/use-eve-agent-vue.mdx

@@ -89,7 +89,7 @@ async function onFileChange(event: Event) {
 
 ## Human-in-the-loop prompts
 
-A tool opts into approval with `needsApproval` ([Tools](../../tools)). When it triggers, the pending request shows up as a `dynamic-tool` part on the latest message at `part.toolMetadata?.eve?.inputRequest`. Read it, then answer through the same session with `send({ inputResponses })`:
+A tool opts into approval with `approval` ([Tools](../../tools)). When it triggers, the pending request shows up as a `dynamic-tool` part on the latest message at `part.toolMetadata?.eve?.inputRequest`. Read it, then answer through the same session with `send({ inputResponses })`:
 
 ```ts
 import type { EveDynamicToolPart, EveMessagePart } from "eve/vue";

package/docs/guides/session-context.md

@@ -3,7 +3,7 @@ title: "Session Context"
 description: "Runtime helpers: ctx.session, ctx.getSandbox, ctx.getSkill, and defineState."
 ---
 
-eve exposes runtime state through the `ctx` parameter passed to tool `execute`, hook handlers, and channel event handlers:
+eve exposes runtime state through the `ctx` parameter passed to tool `execute`, hook handlers, channel event handlers, and connection auth/header resolvers:
 
 - `ctx.session`: session metadata, turn, auth, and parent lineage
 - `ctx.getSandbox()`: live sandbox handle for the current agent
@@ -119,6 +119,7 @@ export const budget = defineState<BudgetState>("myapp.budget", () => ({
 Safe places:
 
 - inside `defineTool(...).execute(input, ctx)`
+- inside connection `auth: (ctx) => provider` and `headers: (ctx) => values` resolvers
 - inside authored callbacks eve runs inside the runtime
 - after asynchronous boundaries inside the same authored execution chain
 

package/docs/reference/typescript-api.md

@@ -51,11 +51,11 @@ export default defineTool({
 | `defineEvalConfig`                                    | `eve/evals`                                   | `evals/evals.config.ts`              | [Evals](../evals/overview)                             |
 | `useEveAgent`                                         | `eve/react`, `eve/vue`, `eve/svelte`          | frontend                             | [Frontend](../guides/frontend/overview)                |
 
-A few non-`define*` helpers round out the set: `disableTool` and `ExperimentalWorkflow` from `eve/tools` (see [Default harness](../concepts/default-harness)), the route verbs `GET`/`POST`/`PUT`/`PATCH`/`DELETE`/`WS` from `eve/channels`, the approval predicates `always`/`once`/`never` from `eve/tools/approval`, and the channel auth helpers `localDev`/`vercelOidc`/`placeholderAuth` from `eve/channels/auth`. To wrap a built-in tool, import its default value from `eve/tools/defaults` (`bash`, `readFile`, `writeFile`, `glob`, `grep`, `webFetch`, `webSearch`, `todo`, `loadSkill`). `AgentWorkflowDefinition` and `AgentWorkflowWorldDefinition` are exported from `eve` for the `defineAgent({ experimental: { workflow } })` config shape.
+A few non-`define*` helpers round out the set: `disableTool` and `ExperimentalWorkflow` from `eve/tools` (see [Default harness](../concepts/default-harness)), the route verbs `GET`/`POST`/`PUT`/`PATCH`/`DELETE`/`WS` from `eve/channels`, the approval policies `always`/`once`/`never` from `eve/tools/approval`, and the channel auth helpers `localDev`/`vercelOidc`/`placeholderAuth` from `eve/channels/auth`. To wrap a built-in tool, import its default value from `eve/tools/defaults` (`bash`, `readFile`, `writeFile`, `glob`, `grep`, `webFetch`, `webSearch`, `todo`, `loadSkill`). `AgentReasoningDefinition` is exported from `eve` for the top-level `defineAgent({ reasoning })` setting. `AgentWorkflowDefinition` and `AgentWorkflowWorldDefinition` are exported from `eve` for the `defineAgent({ experimental: { workflow } })` config shape.
 
 ## Runtime context (`ctx`)
 
-`ctx` is passed to your tool `execute`, hook handlers, and channel event handlers. It is live only while authored code is running, so reaching for it at module top level throws. See [Session context](../guides/session-context) for the full model.
+`ctx` is passed to your tool `execute`, hook handlers, channel event handlers, and connection auth/header resolvers. It is live only while authored code is running, so reaching for it at module top level throws. See [Session context](../guides/session-context) for the full model.
 
 | Member                      | Use                                                                          |
 | --------------------------- | ---------------------------------------------------------------------------- |

package/docs/subagents.mdx

@@ -16,7 +16,7 @@ Every agent gets an `agent` tool by default. The model calls it to delegate a su
 }
 ```
 
-The copy shares the parent's sandbox and tools, and a child's file writes are immediately visible to the parent. That is what makes parallel calls natural: fan out a few copies to fix different files at once. The copy inherits auth and connections, but starts with fresh conversation history and fresh state. If a declared subagent calls `agent`, the child is a copy of _that_ subagent, not the root.
+The copy shares the parent's sandbox and tools, and a child's file writes are immediately visible to the parent. That is what makes parallel calls natural: emit multiple `agent` calls in one response to fan out a small, fixed set of independent subtasks. eve runs that batch concurrently and returns every result before the parent continues. Give children non-overlapping write scopes when they work in the shared sandbox. The copy inherits auth and connections, but starts with fresh conversation history and fresh state. If a declared subagent calls `agent`, the child is a copy of _that_ subagent, not the root.
 
 The parent transfers data to the child through the `message` input it gives the subagent. Do not include sensitive data in a subagent request unless that child and its inherited tools, connections, sandbox, and telemetry path are appropriate for that data.
 
@@ -88,7 +88,7 @@ A declared subagent's tool name is the bare path-derived name, with no prefix. `
 
 Because the name lives in the same runtime tool namespace as authored tools, a subagent named `researcher` collides with a tool named `researcher`. eve rejects the build rather than picking a winner, so keep subagent directory names distinct from tool names.
 
-Do not rely on subagent delegation by itself as an approval boundary. Put sensitive tools behind `needsApproval`, connection approval, route/session authorization, or other controls wherever those tools can be called.
+Do not rely on subagent delegation by itself as an approval boundary. Put sensitive tools behind `approval`, connection approval, route/session authorization, or other controls wherever those tools can be called.
 
 Each delegated subagent spins up its own child session and stream. The parent stream carries only the control-plane events `subagent.called` and `subagent.completed`. To follow the child's full progress, read `subagent.called.data.childSessionId` and subscribe at `GET /eve/v1/session/:childSessionId/stream`.
 

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

@@ -13,7 +13,7 @@ Either way the run parks at `session.waiting`, durably, for as long as it takes
 
 ## Approvals
 
-Approval is a property of a [tool](/docs/tools) that pauses for a person before it runs. Gate a tool with `needsApproval` and the helpers from `eve/tools/approval`:
+Approval is a property of a [tool](/docs/tools) that pauses for a person before it runs. Gate a tool with `approval` and the helpers from `eve/tools/approval`:
 
 ```ts title="agent/tools/refund_charge.ts"
 import { defineTool } from "eve/tools";
@@ -22,8 +22,8 @@ import { z } from "zod";
 
 export default defineTool({
   description: "Refund a charge.",
-  inputSchema: z.object({ chargeId: z.string(), amount: z.number() }),
-  needsApproval: always(), // or once() / never() / a predicate
+  inputSchema: z.object({ tenantId: z.string(), chargeId: z.string(), amount: z.number() }),
+  approval: always(), // or once() / never() / a policy
   async execute(input) {
     return refund(input);
   },
@@ -36,16 +36,53 @@ export default defineTool({
 | `once()`   | Require approval only the first time the tool runs in a session; auto-allow after. |
 | `always()` | Require approval before every call.                                                |
 
-By default, omitted `needsApproval` 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.
+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.
 
-When the decision depends on the input, pass your own predicate instead of a helper. It receives `{ toolName, toolInput, approvedTools }` and returns a boolean. `toolInput` can be undefined, so guard the access. To require approval only when an amount crosses a threshold:
+When the decision depends on the input, pass your own policy instead of a helper. It receives the same session context as tool execution, plus `{ toolName, toolInput, approvedTools }`, and returns an AI SDK 7 approval status synchronously or as a promise. Use `ctx.session.auth.current` to guard by the caller of the current turn and `ctx.session.auth.initiator` to guard by the caller that created the session. Return `"user-approval"` to pause for a person or `"not-applicable"` to continue without a prompt. `toolInput` can be undefined, so guard the access. This policy denies cross-tenant calls, then requires approval only when an amount crosses a threshold:
 
 ```ts
-needsApproval: ({ toolInput }) => (toolInput?.amount ?? 0) > 1000,
+approval: ({ session, toolInput }) => {
+  const callerTenant = session.auth.current?.attributes.tenantId;
+  if (callerTenant === undefined || callerTenant !== toolInput?.tenantId) {
+    return { type: "denied", reason: "Caller cannot access this tenant." };
+  }
+  return (toolInput?.amount ?? 0) > 1000 ? "user-approval" : "not-applicable";
+},
 ```
 
+For compatibility with the previous predicate shape, policies may return booleans: `true` is treated as `"user-approval"` and `false` as `"not-applicable"`. Boolean promises are supported too.
+
+Policies can also return `"approved"` or `"denied"` to decide automatically. Use `{ type: "approved" | "denied", reason }` when the model should receive a reason. The `Approval`, `ApprovalContext`, and `ApprovalStatus` types are exported from both `eve/tools` and `eve/tools/approval`.
+
 Gating a side effect on approval is also how you make non-idempotent work safe across replays: a charge or email that sits behind `always()` can't fire from a re-run step without a fresh human decision.
 
+### Skipping approval for schedule-dispatched turns
+
+`session.auth.current` identifies the caller of this turn. Markdown schedules use the app principal (`authenticator: "app"`, `principalId: "eve:app"`, `principalType: "runtime"`) automatically. A `run` schedule must pass its `appAuth` to `receive(...)` for the child session to use that principal. Match all three fields to skip approval for automated turns while still prompting when a person calls the same tool:
+
+```ts title="agent/tools/refund_charge.ts"
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description: "Refund a charge.",
+  inputSchema: z.object({ chargeId: z.string(), amount: z.number() }),
+  approval: ({ session }) => {
+    const auth = session.auth.current;
+    return auth?.authenticator === "app" &&
+      auth.principalId === "eve:app" &&
+      auth.principalType === "runtime"
+      ? "not-applicable"
+      : "user-approval";
+  },
+  async execute(input) {
+    return refund(input);
+  },
+});
+```
+
+`session` in `approval` has the same shape as `ctx.session` in `execute`: `id`, `auth`, `turn`, and an optional `parent`. If a person later resumes a schedule-started session, `session.auth.current` becomes that person while `session.auth.initiator` remains the app principal. Inspect `initiator` only when the policy should apply to the whole session. Skipping approval on scheduled turns means any non-idempotent side effect will re-fire if a step replays, so pair this pattern with idempotency keys or `once()` where needed.
+
 ## Questions
 
 The built-in `ask_question` tool lets the model pause and ask the user, rather than guessing. It has no `execute` — the model calls it with `{ prompt, options?, allowFreeform? }`:

package/docs/tools/overview.mdx

@@ -46,7 +46,7 @@ eve never runs authored tools during discovery. The model sees descriptors first
 
 ## Gate a tool on human approval
 
-A tool can require a person to sign off before it runs. Set `needsApproval` with the helpers from `eve/tools/approval`:
+A tool can require a person to sign off before it runs. Set `approval` with the helpers from `eve/tools/approval`:
 
 ```ts title="agent/tools/refund_charge.ts"
 import { defineTool } from "eve/tools";
@@ -56,14 +56,14 @@ import { z } from "zod";
 export default defineTool({
   description: "Refund a charge.",
   inputSchema: z.object({ chargeId: z.string(), amount: z.number() }),
-  needsApproval: always(), // or once() / never() / a predicate
+  approval: always(), // or once() / never() / a policy
   async execute(input) {
     return refund(input);
   },
 });
 ```
 
-Approval is one half of eve's [human-in-the-loop](./human-in-the-loop) model — the page covers the `always/once/never` helpers, input-dependent predicates, and how a gated call pauses and resumes durably.
+Approval is one half of eve's [human-in-the-loop](./human-in-the-loop) model — the page covers the `always/once/never` helpers, input-dependent policies, and how a gated call pauses and resumes durably.
 
 ## Shape what the model sees with `toModelOutput`
 

package/docs/tutorial/first-agent.mdx

@@ -10,7 +10,7 @@ Step 1 gets it talking. The scaffold bundles a small sample dataset, so your fir
 ## Prerequisites
 
 - Node 24 or newer and npm.
-- A model credential. The scaffold's default model goes through the [Vercel AI Gateway](../getting-started), so you need `AI_GATEWAY_API_KEY` (or `VERCEL_OIDC_TOKEN` pulled via `vercel link`). A direct provider model like `anthropic("claude-opus-4.8")` instead needs that provider's AI SDK package and key, here `@ai-sdk/anthropic` and `ANTHROPIC_API_KEY`.
+- A model credential. The scaffold's default model goes through the [Vercel AI Gateway](../getting-started), so you need `AI_GATEWAY_API_KEY` (or `VERCEL_OIDC_TOKEN` pulled via `vercel link`). A direct provider model like `anthropic("claude-opus-4-8")` instead needs that provider's AI SDK package and key, here `@ai-sdk/anthropic` and `ANTHROPIC_API_KEY`.
 
 If you have not run eve before, complete [Getting Started](../getting-started) first. Without a credential, "Run the agent" below fails when the runtime tries to reach the model; the dev TUI's `/model` flow walks you through pasting a key or linking a project.