eve 0.32.0 → 0.33.1

package/docs/agent-config.md

@@ -17,6 +17,10 @@ export default defineAgent({
 });
 ```
 
+For a static AI Gateway model ID, you can make the same source change from the
+project root with `eve set --model anthropic/claude-opus-4.8` or from the local
+dev TUI with `/model anthropic/claude-opus-4.8`.
+
 The root `agent.ts` can be omitted when no runtime config is needed. In that case, eve defaults
 to `anthropic/claude-sonnet-5`. When `agent.ts` is present, `model` is required.
 
@@ -45,21 +49,23 @@ Model use is subject to the terms, data-processing commitments, retention behavi
 
 ### Choose the model dynamically
 
-`model` also accepts `defineDynamic({ fallback, events })`. `fallback` is the
-compiled static model: it anchors build-time metadata (routing, credentials,
-context window) and serves whenever no dynamic selection is set.
+`model` also accepts `defineDynamic({ events })`. Each matching handler must
+return the concrete model for its scope; a dynamic model has no compiled
+default.
 
 ```ts title="agent/agent.ts"
 import { defineAgent, defineDynamic } from "eve";
 
 export default defineAgent({
   model: defineDynamic({
-    fallback: "anthropic/claude-sonnet-5",
     events: {
-      "session.started": (_event, ctx) =>
-        ctx.session.auth.initiator?.attributes.plan === "enterprise"
-          ? "anthropic/claude-opus-4.8"
-          : null,
+      "session.started": (_event, ctx) => {
+        if (ctx.session.auth.initiator?.attributes.plan === "enterprise") {
+          return "anthropic/claude-opus-4.8";
+        }
+
+        return "anthropic/claude-sonnet-5";
+      },
     },
   }),
 });
@@ -68,24 +74,28 @@ export default defineAgent({
 Handlers receive the shared [dynamic resolver
 context](./guides/dynamic-capabilities) (`ctx.session`, `ctx.channel`,
 `ctx.messages`) and return a gateway model id, an AI SDK `LanguageModel`, a
-selection object, or `null` to leave the scope unset.
+selection object. Returning `null` or `undefined` fails the turn.
 
 - **Scopes.** `session.started` (once per session), `turn.started` (once per
   turn), `step.started` (every model step). Precedence: step > turn >
-  session > `fallback`. Prefer `session.started`: prompt caches are per
-  model, so every switch re-ingests the conversation at uncached prices.
-- **Failures degrade, never fail the turn.** A resolver that throws or
-  returns an invalid selection logs an error and leaves its scope unset.
-  Build-time validation covers only `fallback`; a selected model without
-  credentials fails at request time.
+  session. Prefer `session.started`: prompt caches are per model, so every
+  switch re-ingests the conversation at uncached prices. If no active
+  selection exists before model-dependent work begins, the turn fails.
+- **Failures stop the turn.** A resolver that throws, returns no model, or
+  returns an invalid selection fails before the provider call. A selected
+  model without valid credentials fails at request time.
 - **Serialization.** Session/turn selections must be model id strings; return
   live `LanguageModel` objects only from `step.started`.
 - **Selection object.** `{ model, modelContextWindowTokens?, modelOptions? }`.
-  Set `modelContextWindowTokens` when the selected model's window differs
-  from the fallback's — it is never inherited. Omitted `modelOptions` reuses
-  the agent-level `modelOptions`.
+  When `modelContextWindowTokens` is omitted, eve resolves it from the AI
+  Gateway catalog and caches successful metadata in durable session state for
+  24 hours. Set it explicitly for an unlisted or custom model. Dynamic agents
+  cannot set sibling `modelContextWindowTokens` or `modelOptions` fields;
+  return per-model values from the handler.
 
-Runtime identity reports a dynamic agent's model as `dynamic:<fallback id>`.
+The `session.started` runtime identity does not include a model id for a
+dynamic agent. Each public `step.started` event reports the concrete `modelId`
+selected for that model call.
 
 ## Reasoning effort
 
@@ -103,6 +113,7 @@ 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.
+Run `eve set --reasoning high` to update this field from the command line.
 
 ## Compaction
 

package/docs/channels/chat-sdk.mdx

@@ -99,22 +99,22 @@ bot.onNewMention(async (thread, message) => {
 
 `options` accepts `{ thread, auth?, title?, mode?, callback?, adapterName?, turnPolicy? }`. `title` sets the eve session's display title without changing the model message; `auth` attaches an authenticated principal to the turn.
 
-### Experimental steering
+### Steering
 
-By default, a message sent while an eve turn is active waits for the next turn. Pass `turnPolicy: "experimental-steer"` to cancel the active turn before sending the new message:
+Messages default to `turnPolicy: "steer"`: a message sent while an eve turn is active is durably buffered, then cancels that turn and starts as its replacement. Set `turnPolicy: "queue"` when the active turn should finish first:
 
 ```ts
 bot.onSubscribedMessage(async (thread, message) => {
   await send(message.text, {
     thread,
-    turnPolicy: "experimental-steer",
+    turnPolicy: "queue",
   });
 });
 ```
 
-This is cancellation-backed steering: the interrupted turn emits `turn.cancelled`, and the replacement message starts a new turn with a new turn ID. Partial output and completed side effects from the interrupted turn are not rolled back. If no turn is active, the message is sent normally. Use the default `turnPolicy: "queue"` when every turn should finish in order.
+Cancellation-backed steering emits `turn.cancelled`, and the replacement message starts a new turn with a new turn ID. Partial output and completed side effects from the interrupted turn are not rolled back. If no turn is active, the message is sent normally. You can set the policy once on `chatSdkChannel({ turnPolicy })` or override it per `send(...)`.
 
-This policy controls overlapping eve turns. Chat SDK's separate `concurrency` option controls overlapping webhook handlers; use `concurrency: "concurrent"` when each inbound message should reach the experimental steering path immediately.
+This policy controls overlapping eve turns. Chat SDK's separate `concurrency` option controls overlapping webhook handlers; use `concurrency: "concurrent"` when each inbound message should reach the steering path immediately.
 
 ### Delivery
 

package/docs/channels/custom.mdx

@@ -109,6 +109,26 @@ await session.reset({ reason: "Retire this session" });
 await session.getEventStream({ startIndex: 12 });
 ```
 
+Message sends use the channel's `turnPolicy`, which defaults to `"steer"`. An accepted message arriving during an active turn is durably buffered before eve cancels that turn and starts the message as a replacement turn. Configure `turnPolicy: "queue"` on `defineChannel(...)` when active turns should finish in order, or override one send:
+
+```ts
+export default defineChannel({
+  turnPolicy: "queue",
+  routes: [
+    POST("/messages", async (request, { from }) => {
+      const body = await request.json();
+      await from(body.threadId).send(body.message, {
+        auth: null,
+        turnPolicy: "steer",
+      });
+      return new Response(null, { status: 202 });
+    }),
+  ],
+});
+```
+
+The same override is available on fixed `Session.send(...)` and cross-channel `to(...).send(...)`. `respond(...)` never steers: it delivers only addressed input responses. Use `cancel()` when you need to stop work without a replacement message.
+
 Attaching does no lookup. The first operation reports whether the ID is active.
 Call `resolveSession(address)` only when you explicitly need to snapshot an
 address's current owner as a fixed handle.

package/docs/channels/discord.mdx

@@ -16,6 +16,7 @@ pnpm eve add channel/discord
 
 The setup guides you through creating a Discord application and bot, then:
 
+- signs you in to Vercel and creates or links a project when needed;
 - validates the bot token;
 - creates a Vercel Connect client and attaches `/eve/v1/discord` as its trigger destination;
 - registers an application command with a required `message` option;

package/docs/channels/eve.mdx

@@ -56,6 +56,8 @@ curl -X POST https://<deployment>/eve/v1/session/wrun_A \
   -d '{"inputResponses":[{"requestId":"req_A","optionId":"approve"}]}'
 ```
 
+Follow-up messages use `turnPolicy: "steer"` by default. If a turn is active, eve buffers the message before cooperatively cancelling that turn, then starts the follow-up as a replacement turn with a new turn ID. Set `turnPolicy: "queue"` on `eveChannel(...)` when follow-ups should wait for active turns to finish. `inputResponses` never steer.
+
 Sending a message to an unknown or terminal session ID returns `409` with
 `{"code":"session_not_active","error":"The session is no longer active.","ok":false}`.
 TypeScript clients expose the stable code as `ClientError.code`. The route never

package/docs/channels/github.mdx

@@ -14,7 +14,7 @@ Run the registry setup from the agent directory:
 eve add channel/github
 ```
 
-The flow checks that the Vercel CLI is authenticated, creates or links a Vercel project when needed, provisions an app-scoped GitHub Connect client, and registers `/eve/v1/github` as a trigger destination. It then installs `@vercel/connect` and writes `agent/channels/github.ts` with the connector UID.
+The flow signs you in to Vercel when needed, creates or links a Vercel project, provisions an app-scoped GitHub Connect client, and registers `/eve/v1/github` as a trigger destination. It then installs `@vercel/connect` and writes `agent/channels/github.ts` with the connector UID.
 
 Vercel Connect creates the GitHub App, receives and verifies its webhooks, and forwards them to the deployed agent. After deploying, open the GitHub App in the Connect dashboard and install it in the organization or account where you want to use it. Add the generated invocation token (for example, `@my-agent`) to a new issue, pull request, or review comment to start a conversation. GitHub may not autocomplete the token or render it as a linked mention.
 

package/docs/channels/linear.mdx

@@ -16,7 +16,7 @@ eve add linear
 
 Select **Linear Channel** in the component checklist. **Linear MCP** is also selected by default if you want the agent to search and update Linear through MCP. Run `eve add channel/linear-agent` instead to install only the channel directly.
 
-The flow checks that the Vercel CLI is authenticated, creates or links a Vercel project when needed, reuses a compatible existing connector when available or provisions an app-scoped Linear Connect client, and registers `/eve/v1/linear` as a trigger destination. It then installs `@vercel/connect` and writes `agent/channels/linear.ts` with the connector UID.
+The flow signs you in to Vercel when needed, creates or links a Vercel project, reuses a compatible existing connector when available or provisions an app-scoped Linear Connect client, and registers `/eve/v1/linear` as a trigger destination. It then installs `@vercel/connect` and writes `agent/channels/linear.ts` with the connector UID.
 
 Vercel Connect creates the Linear app with the `app:assignable` and `app:mentionable` scopes required for Agent Sessions, receives and verifies `AgentSessionEvent` webhooks, and forwards them to the deployed agent. After deploying, open the Linear app in the Connect dashboard and install it in the workspace where you want to delegate work. Then delegate an issue or mention the agent in a Linear Agent Session.
 

package/docs/channels/overview.mdx

@@ -13,6 +13,25 @@ eve ships a base HTTP channel plus first-class platform channels, and you can au
 
 After a channel normalizes input, eve runs the same agent runtime regardless of where the message came from. Tools and instructions do not need channel-specific logic.
 
+## Overlapping messages
+
+Channels default to `turnPolicy: "steer"`. When an accepted message arrives while a turn is active, eve first durably buffers the message, then cooperatively cancels the active turn and starts a replacement turn. The cancelled turn emits `turn.cancelled` followed by `session.waiting`; the replacement starts with a new turn ID. Output already streamed and completed side effects are not rolled back.
+
+Set `turnPolicy: "queue"` on any built-in or custom channel when each turn must finish before the next message starts:
+
+```ts
+export default defineChannel({
+  turnPolicy: "queue",
+  routes: [
+    // ...
+  ],
+});
+```
+
+`from(address).send(...)`, fixed `Session.send(...)`, cross-channel sends, and Chat SDK bridge sends also accept a per-send `turnPolicy` override. Pure `inputResponses` deliveries answer their pending request without steering. Explicit `cancel()` remains the stop-without-replacement operation.
+
+Channel admission still runs first. Ignored mentions, rejected signatures, duplicates, and any other dropped platform events never affect the active turn.
+
 Each channel has its own provider terms, data flow, auth model, and user-consent expectations. Before sending non-public, sensitive, regulated, or production data through a channel, confirm that the channel provider and your configured scopes, signature checks, route auth, and delivery behavior are appropriate for your use case.
 
 ## Where channels live

package/docs/channels/photon.mdx

@@ -7,8 +7,9 @@ Use `photonIMessageChannel` to receive and reply to iMessages through a Photon p
 
 Run `eve add channel/photon-imessage` to create or use a Photon project and register
 your phone number. It then asks whether to configure Vercel Connect or portable
-credentials. With Vercel Connect, eve creates the connector and configures
-Photon’s webhook through Connect. The channel resolves credentials lazily when
+credentials. With Vercel Connect, eve signs you in and creates or links a Vercel
+project when needed, then creates the connector and configures Photon’s webhook
+through Connect. The channel resolves credentials lazily when
 the adapter first initializes:
 
 ```ts title="agent/channels/photon.ts"
@@ -26,6 +27,8 @@ read, and continues the same eve session for every message in an iMessage
 conversation. A new accepted message cooperatively cancels an active turn and
 steers its replacement turn.
 
+Set `turnPolicy: "queue"` when every response should finish before Photon starts the next message.
+
 Customize inbound dispatch with `onMessage`. Return `null` to ignore a message:
 
 ```ts

package/docs/channels/slack.mdx

@@ -18,7 +18,7 @@ The command recommends Vercel Connect, then scaffolds `agent/channels/slack.ts`
 
 ### Recommended: use Vercel Connect
 
-Vercel Connect setup requires an authenticated Vercel CLI and a linked Vercel project. The guided flow creates or reuses a Slack connector, waits for you to install it in a workspace, and registers `/eve/v1/slack` as a trigger destination before writing the channel file.
+Vercel Connect setup requires the Vercel CLI. The guided flow signs you in when needed, creates or links a Vercel project, creates or reuses a Slack connector, waits for you to install it in a workspace, and registers `/eve/v1/slack` as a trigger destination before writing the channel file.
 
 The generated channel resolves credentials at runtime:
 
@@ -236,24 +236,18 @@ export default slackChannel({
 
 `threadContext` requires the matching Slack history scope. Thread helpers reuse messages already loaded within the same inbound handler, and overlapping refreshes share one `conversations.replies` request. 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.
 
-#### Cancel an active turn
+#### Control overlapping turns
 
-Message hooks (`onMessage`, `onAppMention`, and `onDirectMessage`) receive thread-bound session operations directly on `ctx`. Call `ctx.cancel({ turnId? })` before returning `{ auth }` to stop the current turn and queue the new Slack message as replacement input, producing a debounce-like experience:
+Accepted Slack messages use cancellation-backed steering by default: eve buffers the new message, cancels the active turn, and starts a replacement turn. Admission happens first, so ignored mentions and messages rejected by your hooks never cancel work. Set `turnPolicy: "queue"` when every active turn should finish:
 
 ```ts title="agent/channels/slack.ts"
 export default slackChannel({
   credentials: connectSlackCredentials("slack/my-agent"),
-  async onMessage(ctx, message) {
-    const shouldHandle = ctx.isBotMentioned() || (await ctx.isSubscribed());
-    if (!shouldHandle || message.author?.isBot) return null;
-
-    await ctx.cancel();
-    return { auth: null };
-  },
+  turnPolicy: "queue",
 });
 ```
 
-`"accepted"` means the live thread session durably queued the cancellation request. A parked session consumes it as a no-op; `"no_active_turn"` means the thread has no active session owner. Both are successful outcomes, so the hook can still return `{ auth }` to deliver the replacement message. Cancellation never sends input itself. A custom `onInteraction` handler receives the same flat operations, which is useful for a Stop button that should cancel without replacement input.
+Message hooks (`onMessage`, `onAppMention`, and `onDirectMessage`) also receive thread-bound session operations directly on `ctx`. `ctx.cancel({ turnId? })` remains useful for a Stop button: it cancels without sending replacement input. `"accepted"` means the live thread session durably queued that request; a parked session consumes it as a no-op, and `"no_active_turn"` means the thread has no active session owner.
 
 Message and interaction hooks expose every current-owner operation directly on `ctx`:
 

package/docs/concepts/execution-model-and-durability.mdx

@@ -66,7 +66,7 @@ You don't write workflow code directly. Workflow primitives (`start()`, `resumeH
 
 Some work has to wait, including a human approving a [tool](../tools), an interactive OAuth sign-in for a [connection](../connections), or a long-running [subagent](../subagents). At those points the turn parks durably. The workflow suspends and holds no compute until the input it's waiting on arrives (a click, a callback, a child completing), even if that's much later. When it does, the conversation picks up exactly where it left off.
 
-## Message delivery and queueing
+## Message delivery and steering
 
 eve does not maintain a durable FIFO queue of user messages for a session. An
 ID-addressed HTTP delivery and a channel-address delivery both target the
@@ -79,14 +79,11 @@ channel alias. Rekeying replaces only that channel alias. An HTTP-created
 session has the stable ID alias and no channel continuation token. Competing
 channel input is not forwarded to the owner.
 
-When a session is waiting, a delivery through its ID or current channel address
-wakes the session and starts the next turn. When a turn is already active, the
-inbox may accept additional deliveries, but the runtime only drains them at
-specific workflow boundaries. If more than one delivery is ready when the driver
-checks, eve may fold them into the next turn; that drain is best-effort and
-depends on workflow and transport timing.
+When a session is waiting, a delivery through its ID or current channel address wakes it and starts the next turn. Message sends default to `turnPolicy: "steer"`: while a turn is active, the session driver durably buffers the replacement before requesting cooperative cancellation. The interrupted turn emits `turn.cancelled` followed by `session.waiting`, then the replacement starts with a new turn ID. Partial output and completed side effects are not rolled back.
 
-So don't rely on concurrent sends to the same session behaving like a typical ordered chat queue. For deterministic behavior, send one user turn at a time and wait for `session.waiting` before sending the next message to the same session. If your channel can receive bursts while the agent is working, keep your own per-session queue in the channel or app layer, then deliver the next message after the session parks again. Separate sessions still run independently.
+`turnPolicy: "queue"` preserves the message until the active turn settles. If several deliveries are ready when the driver checks, eve may fold adjacent messages into the next turn while preserving their arrival order. Pure `inputResponses` deliveries do not steer; they remain available to the pending request they address.
+
+Every built-in and custom channel accepts a default `turnPolicy`, and imperative message sends can override it. The policy is part of the same durable delivery command as the message, so concurrent senders cannot separate replacement ownership from cancellation intent. Separate sessions still run independently.
 
 ## Subagents
 

package/docs/concepts/sessions-runs-and-streaming.md

@@ -148,17 +148,17 @@ curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId> \
   -d '{"message":"Now send the short version."}'
 ```
 
-The follow-up reuses the same durable session: same history, same state.
+The follow-up reuses the same durable session: same history, same state. Message sends default to cancellation-backed `"steer"`; if a turn is active, eve buffers the follow-up, cancels that turn, and starts the message under a new turn ID. Channels and TypeScript `Session.send(...)` calls can select `turnPolicy: "queue"` when active work should finish first. Structured `inputResponses` never steer.
 
-If the session is waiting on a human-in-the-loop approval, a matching text reply such as `approve` or `cancel` answers the approval. Other follow-up text is held until the approval is answered, so an unrelated message does not implicitly deny the pending tool call.
+If one pending batch is waiting on a human-in-the-loop approval, a matching text reply such as `approve` or `cancel` answers it. Unrelated text starts an ordinary turn immediately without denying the tool call; the approval stays pending and answerable. A later structured `inputResponses` answer keyed by its `requestId` still resumes the original tool call, even after intervening turns.
 
-If the session is waiting on `ask_question`, a follow-up message clears that pending request before the model continues. An exact option match or permitted freeform response answers the question; any other message marks the question unanswered and starts the follow-up turn.
+With one question-only batch, an exact option match or permitted freeform response answers `ask_question`. Any other follow-up marks the question unanswered and starts the new turn. With several approval or question batches pending, eve does not guess which batch plain text addresses: the message starts an ordinary turn and the batches stay open. Use structured responses to target requests unambiguously.
 
-A response is stale when its request is no longer pending: the question or approval was already answered, cleared by a follow-up message, or cancelled. eve delivers a stale response to the model as a new user message, and the model decides whether the old selection still matters. A stale approval never authorizes the earlier tool call; the model must request the action and approval again if they are still needed.
+A structured response matches any currently pending request by ID, not only the newest batch. It becomes stale only after that request was answered, cleared, or cancelled. eve delivers a stale response to the model as a new user message, and the model decides whether the old selection still matters. A stale approval never authorizes the earlier tool call; the model must request the action and approval again if they are still needed.
 
-Responses match pending requests by request ID, so a response to an older request stays a plain user message even while a different question or approval is pending. Like any follow-up message, a stale response clears a pending question and is held while an approval is pending.
+One delivery can answer requests from several batches. eve resumes approval-bearing batches in durable order and carries later answers forward until each batch can resume.
 
-For deterministic ordering, send one follow-up at a time and wait for the next `session.waiting` event before sending another message to the same session. See [message delivery and queueing](./execution-model-and-durability#message-delivery-and-queueing) for the current runtime contract.
+Multiple replacement messages retain their durable arrival order and may be folded into the same replacement turn when they arrive before cancellation settles. See [message delivery and steering](./execution-model-and-durability#message-delivery-and-steering) for the current runtime contract.
 
 ## Cancel the in-flight turn
 

package/docs/guides/dynamic-capabilities.md

@@ -7,26 +7,26 @@ description: "Resolve models, subagents, tools, skills, and instructions at runt
 
 ## Dynamic models
 
-The `model` field in `agent.ts` accepts `defineDynamic({ fallback, events })`.
-Resolvers run at `session.started`, `turn.started`, or `step.started`
-(precedence: step > turn > session > `fallback`); `null` leaves a scope unset
-and failures degrade to the next scope. Prefer `session.started` — prompt
-caches are per model, so switching mid-session re-ingests the conversation at
-uncached prices. See
+The `model` field in `agent.ts` accepts `defineDynamic({ events })`. Resolvers
+run at `session.started`, `turn.started`, or `step.started` (precedence: step >
+turn > session). Every matching handler must return a concrete model. A
+missing, invalid, or throwing selection fails the turn before model-dependent
+work begins. Prefer `session.started` — prompt caches are per model, so
+switching mid-session re-ingests the conversation at uncached prices. See
 [agent configuration](../agent-config#choose-the-model-dynamically) for the
 full contract.
 
-The agent always needs exactly one model, so the compiled fallback anchors
-build-time metadata. Tools, skills, instructions, and subagents default by
-authoring a static entry (or returning `null`), so `fallback` on their
-`defineDynamic` export is a build error.
+Dynamic models do not compile a default model or model metadata. When a
+resolver first selects a model, eve normalizes the selection and resolves any
+omitted context-window metadata from the AI Gateway catalog. Dynamic tools,
+skills, instructions, and subagents may return `null` to omit a capability.
 
 ## Dynamic subagents
 
 Wrap a declared subagent's own `agent.ts` in `defineDynamic` when its
 availability depends on the caller, tenant, environment, or a feature flag.
-Return the child definition to configure and expose it. Return `null` or
-`undefined` to omit it from the parent's model-visible tools.
+Return the child definition to configure and expose it. Return `null` to omit
+it from the parent's model-visible tools.
 
 ```ts title="agent/subagents/finance/agent.ts"
 import { defineAgent, defineDynamic } from "eve";
@@ -44,15 +44,19 @@ export default defineDynamic({
 });
 ```
 
-eve always compiles the subagent's filesystem manifest, including its
-instructions, tools, skills, connections, sandbox, and nested subagents. When
-the resolver selects it, eve injects the returned agent configuration into that
-compiled manifest. Each resolution can return a different model or other
-runtime agent settings. Runtime-selected models must use string model IDs;
-build and Workflow-world configuration cannot be selected at runtime.
+eve always compiles the subagent's filesystem resources, including its
+instructions, tools, skills, connections, sandbox, and nested subagents. It
+does not compile an agent config or placeholder model for a dynamic subagent.
+When the resolver selects the subagent, eve combines the returned config with
+those resources before starting the child session. Each resolution can return
+a different model or other runtime agent settings. A returned local config
+must use a static model; it cannot contain another `defineDynamic` model.
+Runtime-selected models must use string model IDs. Put build configuration on
+the outer `defineDynamic` definition; build and Workflow-world configuration
+cannot be selected in a handler result.
 
 A single-file remote subagent uses the same lifecycle. Return
-`defineRemoteAgent(...)` to expose the selected deployment, or nil to omit it:
+`defineRemoteAgent(...)` to expose the selected deployment, or `null` to omit it:
 
 ```ts title="agent/subagents/finance.ts"
 import { defineDynamic, defineRemoteAgent } from "eve";
@@ -77,7 +81,7 @@ outbound request without entering durable workflow state.
 
 Dynamic subagents support `session.started` and `turn.started`. A turn selection
 shadows the session selection for that turn, including when the turn handler
-returns nil. If a resolver throws or returns an invalid definition, eve logs the
+returns `null`. If a resolver throws or returns an invalid definition, eve logs the
 failure and omits the subagent.
 
 The resolved set applies to local and remote direct delegation and the

package/docs/guides/frontend/overview.mdx

@@ -113,20 +113,41 @@ received attachment as a `file` part on the user message. The part includes `med
 
 ## Human-in-the-loop prompts
 
-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 `respond()`:
+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 at `part.toolMetadata?.eve?.inputRequest`. Scan every message because an unrelated turn can add newer messages while an approval stays open, then answer through the same session with `respond()`:
 
 ```tsx
-const request = agent.data.messages
-  .at(-1)
-  ?.parts.find((part) => part.type === "dynamic-tool" && part.toolMetadata?.eve?.inputRequest)
-  ?.toolMetadata?.eve?.inputRequest;
-
-if (request) {
-  await agent.respond([{ requestId: request.requestId, optionId: "approve" }]);
-}
+const pendingRequests = agent.data.messages
+  .flatMap((message) => message.parts)
+  .flatMap((part) => {
+    if (part.type !== "dynamic-tool" || part.state !== "approval-requested") return [];
+    const request = part.toolMetadata?.eve?.inputRequest;
+    return request ? [request] : [];
+  });
+
+return pendingRequests.map((request) => (
+  <fieldset key={request.requestId}>
+    <legend>
+      {request.kind === "tool-approval"
+        ? "Approval required"
+        : request.kind === "question"
+          ? "Question"
+          : "Session limit"}
+    </legend>
+    <p>{request.prompt}</p>
+    {request.options?.map((option) => (
+      <button
+        key={option.id}
+        onClick={() => void agent.respond([{ requestId: request.requestId, optionId: option.id }])}
+        type="button"
+      >
+        {option.label}
+      </button>
+    ))}
+  </fieldset>
+));
 ```
 
-`request.prompt` and `request.options` give you what you need to render the approve and cancel UI. The default reducer marks the part as responded immediately, then updates it again once eve streams the resumed result.
+For a question with `allowFreeform`, render a text input and send `{ requestId, text }`. The default reducer marks each matching part as responded immediately. Approved tools update again when eve streams their result.
 
 ## Authorization prompts
 

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

@@ -77,26 +77,48 @@ await agent.send([
 
 ## Human-in-the-loop prompts
 
-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.respond(inputResponses)`:
+A tool opts into approval with `approval` ([Tools](../../tools)). When one fires, the pending request rides along on a `dynamic-tool` part at `part.toolMetadata?.eve?.inputRequest`. Scan every message because an unrelated turn can add newer messages while the approval stays open, then answer through the same session with `agent.respond(inputResponses)`:
 
-```ts
-import type { EveDynamicToolPart, EveMessagePart } from "eve/svelte";
-
-const isDynamicToolPart = (part: EveMessagePart): part is EveDynamicToolPart =>
-  part.type === "dynamic-tool";
+```svelte
+<script lang="ts">
+  import { useEveAgent } from "eve/svelte";
 
-const request = agent.data.messages
-  .at(-1)
-  ?.parts.filter(isDynamicToolPart)
-  .map((part) => part.toolMetadata?.eve?.inputRequest)
-  .find((value) => value !== undefined);
+  const agent = useEveAgent();
+  const pendingRequests = $derived(
+    agent.data.messages.flatMap((message) =>
+      message.parts.flatMap((part) => {
+        if (part.type !== "dynamic-tool" || part.state !== "approval-requested") return [];
+        const request = part.toolMetadata?.eve?.inputRequest;
+        return request ? [request] : [];
+      }),
+    ),
+  );
+</script>
 
-if (request) {
-  await agent.respond([{ requestId: request.requestId, optionId: "approve" }]);
-}
+{#each pendingRequests as request (request.requestId)}
+  <fieldset>
+    <legend>
+      {request.kind === "tool-approval"
+        ? "Approval required"
+        : request.kind === "question"
+          ? "Question"
+          : "Session limit"}
+    </legend>
+    <p>{request.prompt}</p>
+    {#each request.options ?? [] as option (option.id)}
+      <button
+        type="button"
+        onclick={() =>
+          void agent.respond([{ requestId: request.requestId, optionId: option.id }])}
+      >
+        {option.label}
+      </button>
+    {/each}
+  </fieldset>
+{/each}
 ```
 
-The find-and-answer flow is identical across frameworks. The [React hook reference](./overview) covers the longer walkthrough.
+For a question with `allowFreeform`, bind a text input and send `{ requestId, text }`. The [React hook reference](./overview) covers the shared behavior.
 
 ## Stop, reset, and resume
 

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

@@ -88,28 +88,51 @@ async function onFileChange(event: Event) {
 
 ## Human-in-the-loop prompts
 
-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 `respond(inputResponses)`:
+A tool opts into approval with `approval` ([Tools](../../tools)). When it triggers, the pending request shows up on a `dynamic-tool` part at `part.toolMetadata?.eve?.inputRequest`. Scan every message because an unrelated turn can add newer messages while the approval stays open, then answer through the same session with `respond(inputResponses)`:
 
-```ts
-import type { EveDynamicToolPart, EveMessagePart } from "eve/vue";
+```vue
+<script setup lang="ts">
+import { computed } from "vue";
+import { useEveAgent } from "eve/vue";
 
 const { data, respond } = useEveAgent();
 
-const isDynamicToolPart = (part: EveMessagePart): part is EveDynamicToolPart =>
-  part.type === "dynamic-tool";
-
-const request = data.value.messages
-  .at(-1)
-  ?.parts.filter(isDynamicToolPart)
-  .map((part) => part.toolMetadata?.eve?.inputRequest)
-  .find((value) => value !== undefined);
+const pendingRequests = computed(() =>
+  data.value.messages.flatMap((message) =>
+    message.parts.flatMap((part) => {
+      if (part.type !== "dynamic-tool" || part.state !== "approval-requested") return [];
+      const request = part.toolMetadata?.eve?.inputRequest;
+      return request ? [request] : [];
+    }),
+  ),
+);
+</script>
 
-if (request) {
-  await respond([{ requestId: request.requestId, optionId: "approve" }]);
-}
+<template>
+  <fieldset v-for="request in pendingRequests" :key="request.requestId">
+    <legend>
+      {{
+        request.kind === "tool-approval"
+          ? "Approval required"
+          : request.kind === "question"
+            ? "Question"
+            : "Session limit"
+      }}
+    </legend>
+    <p>{{ request.prompt }}</p>
+    <button
+      v-for="option in request.options ?? []"
+      :key="option.id"
+      type="button"
+      @click="respond([{ requestId: request.requestId, optionId: option.id }])"
+    >
+      {{ option.label }}
+    </button>
+  </fieldset>
+</template>
 ```
 
-The find-and-answer flow is the same across every framework. The [React hook reference](./overview) covers the longer walkthrough.
+For a question with `allowFreeform`, bind a text input and send `{ requestId, text }`. The [React hook reference](./overview) covers the shared behavior.
 
 ## Stop, reset, and resume