eve 0.83.2 → 0.84.0

package/docs/schedules.mdx

@@ -11,12 +11,12 @@ For creator-owned schedules created and managed at runtime, see [Experimental dy
 
 ## `defineSchedule`
 
-Every schedule provides a `cron` and exactly one of `markdown` or `run`:
+Every schedule provides a `cron` and exactly one of `content` or `run`:
 
 ```ts
 interface ScheduleDefinition {
   cron: string;
-  markdown?: string; // fire-and-forget prompt
+  content?: string; // fire-and-forget prompt
   run?: (args: ScheduleHandlerArgs) => Promise<void> | void; // handler
 }
 
@@ -29,7 +29,7 @@ interface ScheduleHandlerArgs {
 
 `defineSchedule` is a type-level pass-through. The compiler is what enforces the one-of rule.
 
-A TypeScript schedule with `markdown` is compile-only because eve stores the prompt in the manifest. A schedule with `run` remains a runtime entry so the handler can execute. See [Authored module lifecycle](./reference/typescript-api#authored-module-lifecycle).
+A TypeScript schedule with `content` is compile-only because eve stores the prompt in the manifest. A schedule with `run` remains a runtime entry so the handler can execute. See [Authored module lifecycle](./reference/typescript-api#authored-module-lifecycle).
 
 `cron` is a standard 5-field string (`minute hour day-of-month month day-of-week`) with minute granularity. On Vercel, each schedule becomes a Vercel Cron Job, and Vercel evaluates the expression in UTC, so `"0 9 * * 1-5"` fires at 09:00 UTC on weekdays. `eve dev` never fires schedules on their cron cadence. A built app served with `eve start` does run production scheduled tasks. To trigger one while iterating in dev, use the dispatch route below.
 
@@ -42,7 +42,7 @@ import { defineSchedule } from "eve/schedules";
 
 export default defineSchedule({
   cron: "*/5 * * * *",
-  markdown: "Pull open Linear issues and POST a summary to the metrics endpoint.",
+  content: "Pull open Linear issues and POST a summary to the metrics endpoint.",
 });
 ```
 

package/docs/skills.mdx

@@ -7,7 +7,7 @@ A skill is a model-loadable procedure that follows the `SKILL.md` convention. It
 
 ## How loading works
 
-eve scans the files under `agent/skills/` and lists each one's name and description in the system prompt. When a request matches a skill's description (or you name the skill outright), the model loads it with `eve__skill({ name })`, and the skill's markdown becomes the call's result in the active turn. An agent with skills always has the [`eve__skill` tool](./concepts/built-in-tools#eve__search-eve__tool-and-eve__skill). A load reports a `load-skill` action named for the skill, and `t.loadedSkill` asserts it in [evals](./evals/assertions).
+eve scans the files under `agent/skills/` and lists each one's name and description in the system prompt. When a request matches a skill's description (or you name the skill outright), the model loads it with `eve__skill({ name })`, and the skill's markdown becomes the call's result in the active turn. An agent with skills always has the [`eve__skill` tool](./concepts/built-in-tools#eve__search-eve__tool-and-eve__skill). A load reports a `load-skill` action named for the skill, and `t.calledSkill` asserts it in [evals](./evals/assertions).
 
 Listing skills and loading their instructions do not require a sandbox: loading returns static instructions from the compiled agent and dynamic instructions from session state. Only access to supporting package files requires a sandbox. Builds may also prewarm sandbox templates that contain static package files. Supporting files are available under `$HOME/.agents/skills/<skill>/`, with `skills/<skill>/` under the workspace root as the fallback when `$HOME` is unavailable. Sibling references inside `SKILL.md`, such as `references/checklist.md`, are relative to the directory containing that specific `SKILL.md`.
 
@@ -64,7 +64,7 @@ import { defineSkill } from "eve/skills";
 
 export default defineSkill({
   description: "Research unfamiliar topics before answering with confidence.",
-  markdown:
+  content:
     "When the task is novel or ambiguous, gather evidence first, then answer with the key facts and the remaining uncertainty.",
   files: {
     "references/checklist.md": "# Checklist\n\n- Find primary sources.\n",
@@ -72,7 +72,7 @@ export default defineSkill({
 });
 ```
 
-eve generates `SKILL.md` from `markdown`, and each `files` entry becomes a package-relative sibling. Start with plain markdown and move to `defineSkill` only when you hit its limits.
+eve generates `SKILL.md` from `content`, and each `files` entry becomes a package-relative sibling. Start with plain markdown and move to `defineSkill` only when you hit its limits.
 
 A static `defineSkill` module is evaluated during compilation and its resolved definition is stored in the manifest; a dynamic skill module is also retained as a runtime entry. See [Authored module lifecycle](./reference/typescript-api#authored-module-lifecycle).
 
@@ -97,12 +97,12 @@ Supporting files are for the model. After loading a skill, the model reads its r
 
 ## Dynamic skills
 
-To serve a different skill per principal, tenant, or channel (the caller's own team playbook, say), wrap `defineSkill` in a `defineDynamic` resolver keyed on `ctx.session.auth`. See [Dynamic capabilities](./guides/dynamic-capabilities).
+To serve a different skill per principal, tenant, or channel (the caller's own team playbook, say), wrap `defineSkill` in `defineDynamic` and select the attribute it depends on from `ctx.session.auth`. See [Dynamic capabilities](./guides/dynamic-capabilities#dynamic-skills).
 
-Subagent lifecycle events do not re-run skill resolvers. The parent's resolved dynamic skills remain available when it resumes after delegation.
+Delegating to a subagent does not change the parent's dynamic skills. They remain available when the parent resumes after delegation.
 
 ## What to read next
 
 - [Connections](./connections): add tools from external MCP and OpenAPI servers
-- [Dynamic capabilities](./guides/dynamic-capabilities): resolve skills per caller with `defineDynamic`
+- [Dynamic capabilities](./guides/dynamic-capabilities): choose skills per caller with `defineDynamic`
 - [Context control](./concepts/context-control): how skills fit the full context model

package/docs/subagents/index.mdx

@@ -124,45 +124,36 @@ configuration to expose the subagent, or `null` to omit it from the parent's too
 ```ts title="agent/subagents/researcher/agent.ts"
 import { defineAgent, defineDynamic } from "eve";
 
-export default defineDynamic({
-  events: {
-    "session.started": (_event, ctx) =>
-      ctx.session.auth.current?.attributes.research === true
-        ? defineAgent({
-            description: "Investigate ambiguous questions before the parent responds.",
-            model: "anthropic/claude-opus-5.5",
-          })
-        : null,
-  },
-});
+export default defineDynamic((ctx) =>
+  ctx.session.auth.current?.attributes.role === "researcher"
+    ? defineAgent({
+        description: "Investigate ambiguous questions before the parent responds.",
+        model: "anthropic/claude-opus-5.5",
+      })
+    : null,
+);
 ```
 
-Resolvers run at `session.started` or `turn.started`; `step.started` is not
-supported for subagents. A nullish result (`null` or `undefined`) removes the
-subagent's description and tool definition from the model-visible surface.
-The subagent's filesystem manifest is always compiled; a non-nullish result injects
-the returned agent configuration when the child runs.
+eve evaluates the subagent before each parent model call. A nullish result (`null` or `undefined`)
+removes the subagent's description and tool definition from the model-visible
+surface. The subagent's filesystem manifest is always compiled; a non-nullish
+result injects the returned agent configuration when the child runs.
 
-Packaging controls must be available before the resolver runs. Put them on
-`defineDynamic`, rather than the `defineAgent` returned by an event handler:
+Packaging controls must be available at compile time. `defineDynamic` takes only a function;
+put packaging configuration on the root agent instead:
 
-```ts
-export default defineDynamic({
+```ts title="agent/agent.ts"
+import { defineAgent } from "eve";
+
+export default defineAgent({
+  model: "anthropic/claude-opus-5.5",
   build: { externalDependencies: ["native-package"] },
-  events: {
-    "session.started": () =>
-      defineAgent({
-        description: "Use a native package when handling delegated work.",
-        model: "anthropic/claude-opus-5.5",
-      }),
-  },
 });
 ```
 
-The compiler applies `build.externalDependencies` while bundling every authored
-module in that dynamic subagent.
+The root's external dependencies apply when bundling subagent modules too.
 See [Dynamic capabilities](./guides/dynamic-capabilities#dynamic-subagents) for
-scope precedence, failure behavior, and the dispatch-time guard.
+when eve evaluates a subagent, failure behavior, and the dispatch-time guard.
 
 Minimum files:
 
@@ -233,9 +224,9 @@ By default, a subagent named `researcher` collides with an authored tool named `
 
 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 the call's `task.started` and `task.settled` events, `agent.started` when the child session opens, plus interactive `input.requested`, `authorization.required`, and `authorization.completed` events proxied from descendants so the root channel can prompt the user. The parent emits `input.resolved` when it routes an answer back down to the descendant that asked. A tool approval is the exception: the descendant decides it, since its response policy can refuse the person who answered, so the approval stays open on the parent until the descendant settles or resolves it. The parent relays the descendant's `approval.settled` and `input.resolved` for it. On text-only channels, a typed reply that matches an option of the first open prompt, such as `approve` for a tool approval or `continue` for a session limit, answers it as the person who typed it, so a person answers several proxied prompts one message at a time. `task.settled` carries the child's reply as `output` when the call completes, or `error.message` when it fails, along with the same tool `name` and `kind: "agent"` as the call's `task.started`. To follow the child's other progress, pass the `agent.started` event to [`session.agent()`](./guides/client/streaming#follow-a-subagent) on a client session attached to the parent and follow the child with `stream()`. It reads `agent.started.data.streamPath`: the child's own session stream for a local child, or a parent-origin proxy for a remote child, which the parent authenticates to the remote deployment.
+Each delegated subagent spins up its own child session and stream. The parent stream carries the task's `task.started`, the call's `call.started` and `call.settled`, and `child.opened` when the child session opens, plus the approvals, questions, and sign-ins descendants open, relayed as the parent's own `interaction.opened` so the root channel can prompt the user. A relayed interaction's `origin` names the descendant session and request, and `origin.call` the descendant's call. The parent settles a relayed question when it routes an answer back down to the descendant that asked. A tool approval is the exception: the descendant decides it, since its response policy can refuse the person who answered, so the approval stays open on the parent until the descendant settles it. The parent relays that `interaction.settled`. On text-only channels, a typed reply that matches an option of the first open prompt, such as `approve` or `deny` for a tool approval or the budget prompt, answers it as the person who typed it, so a person answers several proxied prompts one message at a time. `call.settled` carries the child's reply as `output` when the call completes, or `error.message` when it fails. To follow the child's other progress, pass the `child.opened` event to [`session.agent()`](./guides/client/streaming#follow-a-subagent) on a client session attached to the parent and follow the child with `stream()`. It reads the event's `stream`: the child's own session stream for a local child, or a parent-origin proxy for a remote child, which the parent authenticates to the remote deployment.
 
-`agent.started` carries the `callId` and `turnId` of the call that opened the session, the call's `taskId`, the agent `name`, and the child's `sessionId`. Later calls with the same `taskId` reach the same session and do not announce it again, so match a child to its calls by `taskId`. A session an authored workflow tool opens with `ctx.agent` is announced the same way, with its `taskId` only when the workflow tool call runs as a task.
+`child.opened` carries its `owner` (the call that opened the session, or the task whose run did), the agent `name`, the child's `sessionId`, and the `stream` path to follow it. Later calls with the same `taskId` reach the same session and do not announce it again, so match a child to its calls by `taskId`: each later call's `call.started` carries it. A session an authored workflow tool opens with `ctx.agent` is announced the same way.
 
 Channels with activity reporting show a subagent's tool activity beneath that subagent's progress item. Activity reporting is best-effort and does not change execution or result delivery.
 
@@ -245,11 +236,11 @@ Subagent model calls automatically retry classified transient provider failures,
 
 A child parks after answering instead of terminating, keeping its session and conversation history alive. Pass the task's `taskId` to the same subagent tool with a new `message` to continue that session. Omitting `taskId` always starts a new child. When a child's turn fails, the call fails and the task ends. A `taskId` that names no task of that subagent tool, including one that ended, fails with `UNKNOWN_TASK`. Any later turn can continue the child, and each continuation runs with the auth of the caller that sends it.
 
-A call with the `taskId` of a child that is still working joins the child's current turn, and that turn's final reply settles both calls. If the turn ends before the child reads the message, the message starts the child's next turn, and that turn's reply settles both calls. Use it to correct or add to work in progress. `eve__task_cancel` with the task's `taskId` cancels the child's current turn and keeps its conversation, so a later call with the same `taskId` continues where it left off.
+A call with the `taskId` of a child that is still working joins the child's current turn, and that turn's final reply settles both calls. If the turn ends before the child reads the message, the message starts the child's next turn, and that turn's reply settles both calls. Use it to correct or add to work in progress. `eve__task_cancel` with the task's `taskId` ends the task and stops the child's current work. Start a new task to delegate again after a cancel.
 
 eve adds a framework-injected `[Tasks]` note to the conversation that lists the working and idle tasks by `taskId` and tool, so the model can find a child to continue. See [Tasks](./tools/tasks) for how the model waits for, corrects, and cancels agent tasks.
 
-The parent holds each child for the life of the task's run, which lasts until the parent session ends. Then eve resets local children and sends authenticated reset requests for remote children. Remote reset is best-effort: an unreachable deployment may retain the parked child until its own session deadline. For [remote agents](./guides/remote-agents), upgrade both deployments before relying on continuation or reset behavior introduced by a newer eve version.
+The parent holds each child for the life of the task's run, which lasts until the parent session ends or its task is cancelled. Then eve requests child shutdown, using authenticated reset requests for remote children. Cleanup is best effort: a child whose inbox or deployment is unavailable may remain running or parked. For [remote agents](./guides/remote-agents), upgrade both deployments before relying on continuation or reset behavior introduced by a newer eve version.
 
 ## When to split
 

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

@@ -9,7 +9,7 @@ Human-in-the-loop (HITL) is any point where the agent durably pauses and waits f
 - **Approvals** — a tool policy allows, denies, or pauses a call for a person to review. The agent decides to call the tool; the policy decides whether it runs automatically or needs a human decision.
 - **Questions** — the agent itself asks the user a clarifying question or a choice mid-turn, and parks until they answer.
 
-Both keep the turn open, and the stream reports `turn.waiting`. The run waits durably, for as long as it takes — seconds or days — and picks back up exactly where it left off once the answer arrives. Channels render the request for you.
+Both keep the turn open, and the stream reports `turn.paused` awaiting the person. The run waits durably, for as long as it takes — seconds or days — and picks back up exactly where it left off once the answer arrives. Channels render the request for you.
 
 ## Approvals
 
@@ -32,12 +32,12 @@ export default defineTool({
 });
 ```
 
-| Helper     | Behavior                                                                           |
-| ---------- | ---------------------------------------------------------------------------------- |
-| `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 a decision model whether to run the exact call or require user approval.       |
+| Helper     | Behavior                                                                     |
+| ---------- | ---------------------------------------------------------------------------- |
+| `never()`  | Never require approval (the default when omitted).                           |
+| `once()`   | Remember approval for this tool for the rest of the session.                 |
+| `always()` | Require approval before every call.                                          |
+| `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.
 
@@ -62,7 +62,9 @@ approval: auto({
 });
 ```
 
-A reusable approval grant applies only after every matching request that is already pending has been resolved. If several calls to a `once()`-gated tool have each produced an approval prompt, approving one does not authorize the others; each visible prompt remains an independent decision. After those pending requests are resolved, later calls in the session are allowed automatically.
+Dynamic tools rebuild their policies when evaluated. Use [`ctx.memo()`](/docs/guides/dynamic-capabilities) to keep external JSON observations used to configure a policy.
+
+Each pending approval needs its own answer. A `once()` approval applies to later calls, not other already-open prompts.
 
 Use the object form of `approval` to replace the default `Approve <tool label>?` text with a tool-specific summary. The `prompt` callback receives the validated `input`, final `toolName`, and `callId`:
 
@@ -86,7 +88,7 @@ export default defineTool({
 
 Channels render this prompt in their approval UI. Slack also includes the complete tool input in a collapsed **Tool input** block so an approver can inspect the original structured value.
 
-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, callId, abortSignal }` (connection tools also get `toolAnnotations`), and returns an AI SDK 7 approval status synchronously or as a promise. Use `abortSignal` for asynchronous policy work so cancellation stops it with the turn. 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:
+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, callId, abortSignal }` (connection tools also get `toolAnnotations`), and returns an AI SDK 7 approval status synchronously or as a promise. Use `abortSignal` for asynchronous policy work so cancellation stops it with the turn. 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
 approval: ({ session, toolInput }) => {
@@ -100,9 +102,15 @@ approval: ({ session, toolInput }) => {
 
 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 `eve/tools/approval`.
+Policies can also return `"approved"` or `"denied"` to decide automatically. Use `{ type: "denied", reason }` when the model should receive a reason for denying the call. A denied call never starts: it settles `call.settled` with `outcome: "rejected"`, `cause: { policy: "approval" }`, and a `TOOL_EXECUTION_DENIED` output, whether the policy denies it as the model calls it or when an approved call is checked again. A tool that runs and throws settles `failed`. An explicit `"approved"` result records `clearedBy: { policy: "approval" }` on `call.started`. A call cleared by a remembered `once()` approval records the same `{ policy: "approval" }`; a call approved by a person records `{ interactionId }`. Calls that need no approval omit `clearedBy`. The `Approval`, `ApprovalConfiguration`, `ApprovalContext`, `ApprovalPolicy`, and `ApprovalStatus` types are exported from `eve/tools/approval`.
+
+Approval is not an exactly-once guarantee for a charge or email. Give non-idempotent side effects their own idempotency keys.
+
+### Remember approval for a tool
 
-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.
+`once()` remembers the latest decision people gave its prompts for the resolved tool name, across turns and context clears, until the session ends. A remembered approval covers later calls to that tool regardless of their input; it does not clear a different tool. A later denial of a `once()` prompt for the tool replaces it, so the next call asks again. When one delivery answers several of those prompts, a denial among its answers stands. Approving a prompt asked by `always()` or by a policy that does not return `once()`'s decision remembers nothing, and so does a wrapping policy that calls `once()` but returns a different status. Existing pending prompts still need their own answers.
+
+A remembered approval is consent, not authorization. Authorize the current caller on every call. Use `always()` or an input-dependent policy when different tenants, environments, or other inputs need separate approval decisions. When wrapping `once()` in another policy, forward the policy context and return its status object unchanged.
 
 ### Authorizing approval responses
 
@@ -139,12 +147,12 @@ export default defineTool({
 
 The `response` policy receives:
 
-- `request`: the stable `requestId`, `callId`, `toolName`, and typed `toolInput` for the call being approved, plus `principal`: the authenticated principal whose turn requested the call, or `null` when that caller was unauthenticated or anonymous. eve captures `request.principal` when the approval is requested, so it stays the same while other people continue the session.
-- `response`: the submitted `decision`, `"approve"` or `"cancel"`, plus `principal`: the authenticated principal that submitted it, including its `principalId`, `principalType`, `authenticator`, and `attributes`. Your route or channel supplies this identity. The policy runs for both decisions, so a responder it rejects can neither approve nor cancel the call.
+- `request`: the stable `interactionId`, `callId`, `toolName`, and typed `toolInput` for the call being approved, plus `principal`: the authenticated principal whose turn requested the call, or `null` when that caller was unauthenticated or anonymous. eve captures `request.principal` when the approval is requested, so it stays the same while other people continue the session.
+- `response`: the submitted `decision`, `"approve"` or `"deny"`, plus `principal`: the authenticated principal that submitted it, including its `principalId`, `principalType`, `authenticator`, and `attributes`. Your route or channel supplies this identity. The policy runs for both decisions, so a responder it rejects can neither approve nor deny the call.
 - `session`: read-only session identity and lineage: `id`, `initiator`, `parent`, and `turn`.
 - `auth`: narrow `getToken(provider, options?)` and `requireAuth(provider, options?)` capabilities bound to the responder. Use these when authorization depends on a provider identity or permission; an interactive provider flow parks durably and then retries the policy.
 
-Return `{ status: "allowed" }` to accept the decision. Return `{ status: "rejected", reason }` to leave the shared request pending so another eligible responder can settle it. When a policy only cares who approves, return `{ status: "allowed" }` for `cancel` so anyone can still dismiss the request.
+Return `{ status: "allowed" }` to accept the decision. Return `{ status: "rejected", reason }` to leave the shared request pending so another eligible responder can settle it. When a policy only cares who approves, return `{ status: "allowed" }` for `deny` so anyone can still dismiss the request.
 
 `session.initiator` is the person who started the session, and `request.principal` is the person who asked for this call. In a shared thread they can differ. Compare the full identity of `response.principal` with `request.principal` to let only the requester settle the call:
 
@@ -180,9 +188,7 @@ export default defineTool({
 });
 ```
 
-When the policy refuses a response, the approval stays pending and the turn stays held. The stream emits `approval.candidate` with `outcome: "pending"`, then `approval.candidate` with `outcome: "rejected"` and the policy's `reason`, then `turn.waiting` with `on: "input"` for the same `turnId`. It does not emit `session.waiting`, so a client that stops reading at a session boundary keeps reading through a refusal. The client finishes the submission and the approval prompt stays answerable. Submitting an answer does not confirm approval: `approval.settled` or `input.resolved` records the server's decision.
-
-Every response a policy evaluates starts the same way, not only refusals. eve first records the response as an `approval.candidate` with `outcome: "pending"`, then runs the policy so slow policy work cannot lose the response. An allowed response then emits `approval.settled` and `input.resolved`. An approval without a `response` policy settles directly and emits no `approval.candidate`. A candidate can also end with `failed`, `timed-out`, or `stale`; inspect `approval.candidate` events for the reason.
+When the policy refuses a response, its `response.settled` reports `outcome: "refused"` and the approval stays open for another answer. Submitting an answer does not approve the call on its own: wait for `interaction.settled` to confirm the decision.
 
 ### Skipping approval for schedule-dispatched turns
 
@@ -225,36 +231,38 @@ The user can always type their own answer instead of picking an option, so the m
 ```ts title="agent/tools/ask_question.ts"
 import { askQuestion } from "eve/tools/ask_question";
 
-export default askQuestion();
+export default askQuestion;
 ```
 
 `ask_question` is an ordinary [workflow tool](/docs/tools/workflows) built on `ctx.ask()`. Write your own workflow tool with `ctx.ask()` when you need a different schema or want to act on the answer in the same call. Without any asking tool, the model asks in its reply text and the user's next message carries the answer.
 
-In a custom workflow tool, an answered `ctx.ask()` returns the authenticated responder's `authenticator`, `principalId`, and `principalType` when that identity is available. It does not include channel attributes. `ctx.session.auth.current` remains the run's auth snapshot; use the response's `responder` to identify who answered.
+In a custom workflow tool, an answered `ctx.ask()` returns the authenticated responder's `id`, `type`, and optional `issuer` when that identity is available. It does not include channel attributes. `ctx.session.auth.current` remains the run's auth snapshot; use the response's `responder` to identify who answered.
 
 ## How pause and resume works
 
 Approvals and questions share one protocol:
 
 1. A tool call needs approval, or a workflow tool such as `ask_question` calls `ctx.ask()`.
-2. eve emits an `input.requested` stream event carrying the pending requests.
-3. The run parks durably, for as long as it takes. The turn stays open: the stream emits `turn.waiting`, and after the answer the turn resumes under the same `turnId`. That `turn.waiting` carries `on: "input"`, since a person must act.
-4. The client answers with `inputResponses` (structured, keyed by `requestId`) or a normal follow-up `message`. A follow-up whose text matches an option ID, option label, or numeric option index resolves automatically, including approval options such as `approve` and `cancel`.
+2. eve emits an `interaction.opened` fact for each pending request.
+3. The run parks durably, for as long as it takes. The turn stays open: the stream emits `turn.paused` awaiting those interactions, and after the answer the turn runs on under the same `turnId`.
+4. The client answers with `answers` (structured, each naming its `interactionId`) or a normal follow-up `message`. A follow-up whose text matches an option ID, option label, or numeric option index resolves automatically, including approval options such as `approve` and `deny`.
 
-To tell the model why a call was denied, send `text` with the `cancel` response, for example `{ requestId, optionId: "cancel", text: "Only the three-pack." }`. The model receives the note quoted in the denial result, marked as written by the person who denied the call, who may not be the user. The note is also visible to anyone who can read the session stream, in `input.resolved`.
+To tell the model why a call was denied, send `text` with the `deny` response, for example `{ interactionId, optionId: "deny", text: "Only the three-pack." }`. The model receives the note quoted in the denial result, marked as written by the person who denied the call, who may not be the user. The note is also visible to anyone who can read the session stream, in the `response.submitted` and `interaction.settled` facts.
 
-For `ctx.ask()` questions from tools and prompts proxied from subagents, a follow-up message answers the first open request, as described in [Several requests at once](#several-requests-at-once). The message must match an option, or the question must allow free text. Otherwise the message follows the session's `turnPolicy`. A steering message, the default, aborts the `ctx.abortSignal` of each `execute` workflow tool call the turn waits on, so a question such a call asked, such as `ask_question`'s, is withdrawn and resolves as `cancelled`. The model reads the message once those calls settle.
+For `ctx.ask()` questions from tools and prompts proxied from subagents, a follow-up message answers the first open request, as described in [Several requests at once](#several-requests-at-once). The message must match an option, or the question must allow free text. Otherwise the message follows the session's `turnPolicy`. A steering message, the default, aborts the `ctx.abortSignal` of each `execute` workflow tool call the turn waits on, so a question such a call asked, such as `ask_question`'s, is withdrawn: its interaction settles `withdrawn`. The model reads the message once those calls settle.
 
-Each request includes a `kind` discriminator: `tool-approval`, `question`, or
-`session-limit`. Clients should use `kind` to choose behavior and presentation.
-`requestId` identifies the request to answer, and `action.callId` identifies the
-tool call that raised it; neither encodes the request's semantics.
+On the stream, each interaction's `request.kind` is `approval`, `question`, `budget`, or `sign-in`,
+and its `subject` names the call, task, or turn it is about. Clients read the same interaction as an
+`Interaction`, with the same nested `request.kind`; use it to choose behavior and presentation, and keep a
+default branch, since a later release can add a kind. `interactionId` identifies the interaction to
+answer, and `call.callId`, when present, identifies the call it is about; neither encodes the
+interaction's semantics.
 
 The run picks back up exactly where it parked. Because the pause is durable, nothing is held in memory while it waits — the process can restart and the parked turn survives.
 
-When a subagent requests input, eve emits the same `input.requested` event on its parent session. Answering through that parent session routes the response directly to the blocked child without invoking the parent model.
+When a subagent requests input, its parent session relays it as its own `interaction.opened`, with `origin` naming the child session and request, and `origin.call` naming the child's call. Answering through that parent session routes the response directly to the blocked child without invoking the parent model.
 
-A message from the parent agent to a subagent never answers the subagent's tool approval or session-limit request, even when its text matches an option such as `approve` or `continue`. Only a person's structured answer, routed through the parent session, settles these requests. The subagent still receives the parent's message as an ordinary message. It steers the turn past a pending approval, which resolves as `ignored`, and waits behind a session-limit request until a person answers it.
+A message from the parent agent to a subagent never answers the subagent's tool approval or session-limit request, even when its text matches an option such as `approve` or `continue`. Only a person's structured answer, routed through the parent session, settles these requests. The subagent still receives the parent's message as an ordinary message. It steers the turn past a pending approval, whose interaction settles `withdrawn`, and waits behind a session-limit request until a person answers it.
 
 Approval is consent only. An approved tool call runs with the requesting user's identity, connections, and credentials, including its policy recheck. The approver's access is never lent to the call. Subsequent tool calls in the turn also stay with the original owner.
 
@@ -279,11 +287,11 @@ export default defineTool({
 });
 ```
 
-For approval requests, a follow-up message that doesn't match an option steers the turn instead of answering it. eve cancels the turn's pending approval, so the call doesn't run and `input.resolved` reports `outcome: "ignored"`, and the model reads the message next. This happens even when the message is sent with `turnPolicy: "queue"`, because a turn held on a person can't end until they act. Calls the person already approved in the same batch still run. A message from someone other than the person the turn serves waits until the turn ends. Cancelling the turn withdraws its approval: the call doesn't run, `input.resolved` reports `outcome: "cancelled"`, and a later answer to it approves nothing.
+For approval requests, a follow-up message that doesn't match an option steers the turn instead of answering it. eve withdraws every approval nobody has answered: each interaction settles `withdrawn`, its call settles `rejected` without running, and the model reads the message next. This happens even when the message is sent with `turnPolicy: "queue"`, because a turn held on a person can't end until they act. Approvals that already have an answer settle on it, so calls the person already approved still run. A message from someone other than the person the turn serves waits until the turn ends. Cancelling the turn interrupts its approval: the call doesn't run, the interaction settles `interrupted`, and a later answer to it approves nothing.
 
 ### Several requests at once
 
-A turn can wait on more than one request, such as two `ctx.ask()` questions a workflow tool asks with `Promise.all`, or approvals for two tool calls the model made in one step. A follow-up message answers only the first open request: a [runtime limit](/docs/agent-config#runtime-limits) continuation prompt if one is open, and otherwise the request eve asked for first, in the order of its `input.requested` events.
+A turn can wait on more than one request, such as two `ctx.ask()` questions a workflow tool asks with `Promise.all`, or approvals for two tool calls the model made in one step. A follow-up message answers only the first open request: a [runtime limit](/docs/agent-config#runtime-limits) continuation prompt if one is open, and otherwise the request eve asked for first, in the order of its `interaction.opened` facts.
 
 The message answers that request when it matches one of its options, or when the request accepts free text. Otherwise the message is not an answer and follows the rules above. To answer several requests by text, send one message per request.
 
@@ -297,9 +305,9 @@ See [Sessions, runs & streaming](/docs/concepts/sessions-runs-and-streaming) for
 
 Channels turn requests into native UI: the Slack adapter renders approvals as buttons and questions as select menus, and writes the user's choice back as the answer. You get this for free on every [channel](/docs/channels/overview).
 
-From your own frontend, scan all messages for pending requests and answer through the same session — see [Building a frontend](/docs/guides/frontend/overview#human-in-the-loop-prompts) for the client-side reducer and `inputResponses` shape.
+In your own frontend, use `openInteractions(view)` and `respond([{ interactionId, optionId }])` on the same session. See [Building a frontend](/docs/guides/frontend/overview#human-in-the-loop-prompts).
 
-You can answer while a turn is running, such as the second approval of a batch while the first answer is still settling. The default message reducer waits for server confirmation before marking any input request answered. A submitted answer marks its request `responded` in `data.inputs` until `approval.settled` or `input.resolved` arrives; submitting a response alone does not resolve an approval, question, or session-limit prompt. Answering a request that is no longer open rejects without a server request. The `client.input.responded` event remains a submission notification for custom reducers, not confirmation that the server accepted the answer.
+You can answer while other work runs. An interaction stays `open` until `interaction.settled`; the frontend example shows how to query pending prompts.
 
 ## What to read next
 

package/docs/tools/overview.mdx

@@ -123,7 +123,7 @@ eve does not append the sentence for a function, because whether the call ends t
 
 The turn ends only when every tool call in the model's step can end the turn and succeeds, and every `endsTurn` function returns `true`. Otherwise the model receives the results and continues as usual. Text the model writes before the call is narration, so channels do not post it as the reply. While [tasks](/docs/tools/tasks) are still working, the turn waits for them and then calls the model again.
 
-eve ignores `endsTurn` in delegated sessions, which must return a reply to their caller, and on turns that request structured output; the model does not see the appended sentence there, and eve does not call an `endsTurn` function. `defineWorkflowTool` rejects `endsTurn` at build time. Dynamic tool entries accept `endsTurn` too, including a function. eve replays the function from a durable descriptor, as it does `execute`. To end a turn without taking any other action, add the opt-in [`no_reply`](/docs/concepts/built-in-tools#no_reply) tool.
+eve ignores `endsTurn` in delegated sessions, which must return a reply to their caller, and on turns that request structured output; the model does not see the appended sentence there, and eve does not call an `endsTurn` function. `defineWorkflowTool` rejects `endsTurn` at build time. Dynamic tool entries also accept `endsTurn`, including the function form. To end a turn without taking any other action, add the opt-in [`no_reply`](/docs/concepts/built-in-tools#no_reply) tool.
 
 ### Label tool activity
 
@@ -174,7 +174,7 @@ export default defineTool({
 });
 ```
 
-eve publishes earlier yields as `action.partial` stream events. When the durable
+eve publishes earlier yields as `call.progress` stream records. When the durable
 writer is busy, eve may keep only the newest adjacent snapshot for a call. The
 snapshot is visible to channels, hooks, and clients but never enters model
 history or `toModelOutput`; only the final yield does. Treat snapshots as
@@ -193,7 +193,7 @@ action complete.
 eve normalizes and bounds projected text before rendering it. If either
 callback throws or returns an empty string, eve keeps the existing activity
 label. `label.complete` does not run for failed or rejected tool calls. The
-full values remain available in `action.partial` and `action.result`; renderers
+full values remain available in `call.progress` and `call.settled`; renderers
 receive only the projected text.
 
 ### Durable waits
@@ -229,10 +229,10 @@ answer from the human.
 It does not by itself create a durable wait for a person, timer, or external event. The value's
 meaning depends on the executor:
 
-| Executor             | Ordinary `yield value`                                                                  | Final output                                                                                                |
-| -------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| `defineTool`         | Earlier values are `action.partial` snapshots; the final yield becomes the tool result. | Last yielded value; a generator `return` value is ignored.                                                  |
-| `defineWorkflowTool` | Every yield is an `action.partial` snapshot.                                            | Explicit return value; falls back to the last yield if the return is `null` or `undefined`, then to `null`. |
+| Executor             | Ordinary `yield value`                                                                 | Final output                                                                                                |
+| -------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `defineTool`         | Earlier values are `call.progress` snapshots; the final yield becomes the tool result. | Last yielded value; a generator `return` value is ignored.                                                  |
+| `defineWorkflowTool` | Every yield is a `call.progress` snapshot.                                             | Explicit return value; falls back to the last yield if the return is `null` or `undefined`, then to `null`. |
 
 Progress snapshots do not enter model history as intermediate tool results. The final output
 selected by the rules above becomes the tool result.
@@ -251,19 +251,21 @@ examples.
 - `ctx.session`: session metadata, turn, auth, parent lineage.
 - `ctx.callId`: the id of the current tool call, carried by the call's [stream events](/docs/concepts/sessions-runs-and-streaming) and approval context.
 - `ctx.toolName`: the final runtime name the model called, including any namespace qualification.
-- `ctx.messages`: the model input for the step that requested this call, the same messages a `step.started` [dynamic resolver](/docs/guides/dynamic-capabilities) reads.
+- `ctx.messages`: the model input for the step that requested this call, the same messages a [dynamic capability's](/docs/guides/dynamic-capabilities) `ctx.messages()` returns before that call.
 - `ctx.abortSignal`: aborts when the active turn is cancelled. Pass it to cancellation-aware work; sandbox sessions from `ctx.getSandbox()` are already bound to it.
 - `ctx.getSandbox()`: the live [sandbox](/docs/sandbox) handle.
 
 Running in the app runtime is what lets a tool import shared code from `lib/`, read `process.env`, and take part in eve’s durable pause/resume model.
 
-eve never runs authored tools during discovery. The model sees descriptors first, and only what it actually calls gets executed. Completed steps never re-run; eve replays the recorded result. A step interrupted mid-execution re-runs, so make non-idempotent side effects like charges or emails idempotent, or gate them with approval.
+eve never runs authored tools during discovery. The model sees descriptors first, and only what it calls gets executed. Completed steps replay their recorded result. An interrupted step runs again from its checkpoint, but a call it already started does not run again: the model reads that the call may have taken effect, and decides whether to call it again.
+
+Use operation-specific idempotency keys for external writes such as charges or emails. Approval records consent; it does not deduplicate an operation. See [Crash recovery](/docs/concepts/execution-model-and-durability#resuming-after-a-crash).
 
 ## When a tool throws
 
-If an authored tool's `execute` function throws, eve records a failed `action.result` and gives the error to the model as a tool error. The model can respond, choose another action, or call the tool again. eve does not automatically call the tool again based on the exception type, an upstream HTTP status, or a `retryable` property.
+If an authored tool's `execute` function throws, eve records the call as `call.settled` with `outcome: "failed"` and gives the error to the model as a tool error. The model can respond, choose another action, or call the tool again. eve does not automatically call the tool again based on the exception type, an upstream HTTP status, or a `retryable` property.
 
-Authored tools have no public terminal-error class or retry policy for thrown exceptions. Handle retry policy inside the tool when the operation is safe to retry, and return or throw an actionable error when it is not. Do not rely on that distinction to protect a write: an interruption before the durable step completes can re-run the step and execute the tool again even if the first request reached the upstream service.
+Authored tools have no public terminal-error class or retry policy for thrown exceptions. Handle retry policy inside the tool when the operation is safe to retry, and return or throw an actionable error when it is not. Do not rely on that distinction to protect a write: the model can issue a fresh call, and authored workflow steps have their own durable retries. A tool-call ID does not deduplicate an application operation across fresh calls.
 
 Protect non-idempotent operations with the strongest mechanism the service supports:
 
@@ -304,7 +306,7 @@ toModelOutput(output) {
 },
 ```
 
-`toModelOutput` receives the final, typed `execute` return and only affects the model. Channel event handlers and hooks still get the full output on `action.result`, so a channel can render rich platform output (Slack Block Kit, say) the model never sees. Return `{ type: "text", value }` for a summary, or `{ type: "json", value }` for a smaller object.
+`toModelOutput` receives the final, typed `execute` return and only affects the model. Channel event handlers and hooks still get the full output on `call.settled`, so a channel can render rich platform output (Slack Block Kit, say) the model never sees. Return `{ type: "text", value }` for a summary, or `{ type: "json", value }` for a smaller object.
 
 Tool outputs must be JSON-serializable. Return plain objects, arrays, strings, numbers, booleans, or `null`; convert values like `Date`, `Map`, `Set`, `NaN`, and cyclic objects before returning them from `execute` or from a `{ type: "json" }` `toModelOutput`.
 

package/docs/tools/tasks-upgrade.md

@@ -4,6 +4,9 @@ description: "Move workflow tools, agent calls, clients, hooks, and evals from b
 url: /tools/tasks-upgrade
 ---
 
+> This guide names session events as they were before stream version 27. To move those events to
+> v27 facts, see [Upgrade to v27 session events](/docs/concepts/upgrade-to-v27-events).
+
 This release replaces background tasks with [tasks](/docs/tools/tasks). Every change below breaks
 the previous API. Work through the sections that apply to your agent. A workflow tool that uses
 none of `execution: "background"`, `dismissible`, or `ctx.agent` keeps its code: `execute(input,
@@ -141,7 +144,7 @@ Hooks subscribe the same way:
 +      if (event.data.status !== "completed") return;
 ```
 
-The eval assertion `t.calledSubagent(name, { status })` keeps its API and reads task events.
+The eval assertion `t.calledSubagent` is now `t.calledAgent(name, { status })` and reads call facts; see [Assertions](/docs/evals/assertions#the-matcher-mini-language).
 
 ## Handle open turns in clients
 
@@ -183,6 +186,10 @@ client that accepts only versions up to 25 fails the stream with an unsupported-
 
 ## Upgrade remote agents before their callers
 
+Later eve releases no longer serve protocol-1 callers or accept protocol-1 remote agents. Upgrade
+every caller and remote agent past 0.68 before you upgrade any of them past that later release.
+The rest of this section describes this release.
+
 The remote agent protocol is now version 2. Deploy each [remote agent](/docs/guides/remote-agents)
 before the deployments that call it. A remote agent on this release still serves callers on eve 0.66
 through 0.68, which speak protocol 1. It runs their turns, sends each result to their callback, and
@@ -204,3 +211,8 @@ Upgrade a caller after every remote agent it calls. A caller on this release acc
 remote agent's results and failures, but that remote agent's approvals and sign-in requests don't
 reach the caller. Any other protocol mismatch fails the call at start, with an error that names
 both versions.
+
+Upgrade a caller and its remote agents together, or let the remote agents' in-flight work finish
+first. A remote agent's callbacks go to the caller's current production deployment, so approvals,
+questions, and sign-ins that an earlier remote agent sends after the caller upgrades are rejected
+and never reach the caller. The caller's own sessions stay on the deployment that started them.