eve 0.67.2 → 0.69.0

package/docs/channels/custom.mdx

@@ -3,7 +3,7 @@ title: "Custom Channels"
 description: "Author custom HTTP and WebSocket channels with routes, events, metadata, continuation tokens, and file uploads."
 ---
 
-When eve doesn't ship a channel for your surface, you build one. Custom channels expose HTTP or WebSocket endpoints, parse incoming requests, start or resume sessions, observe runtime events, and own delivery back to your platform.
+Build a custom channel to connect an HTTP or WebSocket endpoint to your agent. It can host a conversation or pass incoming events to another channel.
 
 ## File location and identity
 
@@ -74,6 +74,15 @@ the exact session, while `channel.continuation` exposes the current address and
 receives only `(eventData, channel)` because it runs outside session context;
 its event data contains `sessionId` directly.
 
+A channel that renders questions and approvals from `input.requested` can handle
+`input.resolved` to learn when each request ends, however it ended: answered from
+the channel, answered by a plain-text reply, or withdrawn. A request that a
+workflow tool run relays, from its own `ctx.ask()` or from a session it opened
+with `ctx.agent`, also resolves as `cancelled` when that run ends before anyone
+answers. Every request relayed from a task, workflow tool call, or subagent does
+the same when the turn is cancelled. Each resolution carries the `requestId` and
+an `outcome` such as `answered`, `approved`, or `cancelled`.
+
 `channel.continuation.token` is always the channel-local address accepted by
 `from()`, `resolveSession()`, and `alias()`. Framework namespace prefixes are not
 part of the authored channel API.
@@ -131,6 +140,8 @@ Message sends use the channel's `turnPolicy`, which defaults to `"steer"`. Befor
 
 A sent delivery can interrupt generation before your `deliver` hook runs. If the hook ignores the correction, eve resumes the original request with its original auth, delivery provenance, and channel state. Filter events before `send(...)` when they should never interrupt generation.
 
+Every `send()` and `respond()` delivery passes its `state` option to your channel's `deliver(payload, channel)` hook as `payload.state`, including deliveries to an existing session. Use it for values that belong to one delivery, such as the author of a message. The hook decides what to merge into `channel.state`; eve seeds `channel.state` from `state` only when `send()` creates the session.
+
 Configure `turnPolicy: "queue"` on `defineChannel(...)` when messages should wait for the active turn to finish, or override one send:
 
 ```ts
@@ -155,6 +166,58 @@ 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.
 
+## Wrap an existing channel's routes
+
+A channel value can be spread into a new object with replaced `routes`. eve keeps the channel's adapter, events, and build metadata (such as the Slack app manifest) on the spread copy, so `{ ...channel, routes }` compiles and runs like the original.
+
+The built-in Slack, Teams, and Telegram channels, and the Chat SDK bridge's `send`, hand every inbound message to `from(address).send(message, options)`. A route wrapper that replaces `send` on the source returned by `from(address)` therefore sees each inbound message, and a rejected delivery reaches the wrapper as an error:
+
+```ts title="agent/channels/slack.ts"
+import type { RouteHandlerArgs } from "eve/channels";
+import { slackChannel, type SlackChannelState } from "eve/channels/slack";
+
+const slack = slackChannel();
+
+function reportFailedDeliveries(
+  args: RouteHandlerArgs<SlackChannelState>,
+): RouteHandlerArgs<SlackChannelState> {
+  return {
+    ...args,
+    from(address) {
+      const source = args.from(address);
+      return {
+        ...source,
+        async send(message, options) {
+          try {
+            return await source.send(message, options);
+          } catch (error) {
+            console.error("Slack delivery failed", { address, error });
+            throw error;
+          }
+        },
+      };
+    },
+  };
+}
+
+const channel: typeof slack = {
+  ...slack,
+  routes: slack.routes.map((route) =>
+    route.transport === "websocket"
+      ? route
+      : {
+          ...route,
+          handler: (request: Request, args: RouteHandlerArgs<SlackChannelState>) =>
+            route.handler(request, reportFailedDeliveries(args)),
+        },
+  ),
+};
+
+export default channel;
+```
+
+Keep each route's `method` and `path` unless you mean to move the endpoint.
+
 ## Operation semantics
 
 - `cancel` cooperatively stops the active turn. Confirm it with `turn.cancelled`
@@ -232,45 +295,54 @@ The bridge server does not listen on its own port. It receives only upgrade even
 
 ## Cross-channel hand-off
 
-Route handlers can start or resume an agent session on a different channel via `ctx.to(channel, target).send(message, options)`. This is an agent hand-off: the message becomes turn input and invokes the model on the destination channel. Use it when an inbound request should pivot the conversation, such as an incident webhook that opens an investigation thread in Slack.
+Use `ctx.to(channel, target).send(message, { auth })` in a route handler to start or resume a conversation on another channel. The agent runs and replies on the destination channel. The hand-off doesn't start a session on the source channel, which returns only its HTTP response.
 
-To post a provider notification without starting an agent turn, call the destination provider's API instead. If that notification must survive process failures, use an application-owned outbox; see [Durable cross-channel notifications](../patterns/durable-cross-channel-notifications).
+This webhook filters incoming events and asks the agent to investigate in Slack. Import the destination channel's default export; `verifyAndParseEvent` is a helper you implement in your application.
 
-```ts
+```ts title="agent/channels/intake.ts"
 import { defineChannel, POST } from "eve/channels";
+
+import { verifyAndParseEvent } from "../lib/inbound-events";
 import slack from "./slack";
 
 export default defineChannel({
   routes: [
-    POST("/incident", async (req, ctx) => {
-      const incident = await req.json();
+    POST("/intake/events", async (req, ctx) => {
+      const event = await verifyAndParseEvent(req);
+      if (!event) return new Response("unauthorized", { status: 401 });
+      if (event.kind !== "actionable") return new Response("ok");
 
       ctx.waitUntil(
         ctx
           .to(slack, { channelId: "C0123ABC" })
-          .send(`Investigate ${incident.reference}: ${incident.title}`, {
+          .send(`Investigate ${event.reference}: ${event.summary}`, {
             auth: {
-              authenticator: "incidentio",
+              authenticator: "intake",
               principalType: "service",
-              principalId: incident.actor.id,
-              attributes: { reference: incident.reference, severity: incident.severity },
+              principalId: event.source,
+              attributes: {},
             },
           }),
       );
-
       return new Response("ok");
     }),
   ],
 });
 ```
 
-Semantics:
+Before sending:
+
+- Verify the provider's signature and validate the payload, including size limits. Derive `event.source` from the verified sender, not an untrusted payload field.
+- Filter out events that should not reach the agent.
+- Deduplicate retried events in your application if duplicates would cause unwanted sessions or posts. `send(...)` does not deduplicate them.
+
+The supplied `auth` identifies who started the session, available to tools and event handlers as `session.auth.initiator`.
+
+The destination's `receive` hook defines the target fields and how they map to a session. See [Slack proactive sessions](./slack#proactive-sessions) for its target options. To let people continue the conversation, configure the destination's inbound handlers to accept follow-ups.
+
+`ctx.to(...)` is a route-handler API, not a method on every platform callback. [Handler-form schedules](../schedules#handler-form-run) provide the same operation as `to(...)`.
 
-- The target channel's authored `receive(input, { from })` hook owns the continuation-token format and initial state. Callers supply the target to `to(...)`, then the message and auth to `send(...)`.
-- `auth` flows through to `session.auth.initiator` so the target's event handlers and the agent's tools can read who started the session.
-- Calling `ctx.to(...).send(...)` does not also start a session on the current channel. The inbound channel's response is whatever the route handler returns explicitly.
-- `send(...)` is not a direct provider-message API. It supplies input to the agent on the destination channel.
-- The first argument is the target channel module's default export. Import it directly from `agent/channels/<name>.ts`. Identity is matched by reference.
+For notifications that don't need an agent turn, use the platform's API instead. See [Durable cross-channel notifications](../patterns/durable-cross-channel-notifications) when those posts also need retries.
 
 ## Channel metadata
 

package/docs/channels/eve.mdx

@@ -103,7 +103,7 @@ Stream a session as newline-delimited JSON from `GET /eve/v1/session/:sessionId/
 
 ### Cancel a turn
 
-Post to `/eve/v1/session/:sessionId/cancel` to request cancellation of the active turn. You can include the observed `turnId` to keep a late request from cancelling a newer turn. Include `tasks: true` to also cancel every background task owned by the session, including while the session is parked. Cancellation is asynchronous; confirm the turn boundary on the stream as `turn.cancelled` followed by `session.waiting`, and inspect task state in a later turn to confirm task cancellation.
+Post to `/eve/v1/session/:sessionId/cancel` to request cancellation of the active turn. You can include the observed `turnId` to keep a late request from cancelling a newer turn. Cancellation is asynchronous; confirm the turn boundary on the stream as `turn.cancelled` followed by `session.waiting`.
 
 See [Cancel the in-flight turn](../concepts/sessions-runs-and-streaming#cancel-the-in-flight-turn) for response statuses, HTTP status codes, subagent cancellation, and race behavior.
 

package/docs/channels/mcp.mdx

@@ -187,7 +187,7 @@ The invocation response is discriminated by `status`:
 - `working`: work is active; continue polling according to `pollAfterMs`.
 - `input_required`: present `inputRequests`, then send the complete answer batch through `agent_update`. A successful update returns the current invocation state.
 - `authorization_required`: present the returned sign-in URL, user code, or instructions. The connection callback resumes the invocation automatically; continue polling.
-- `completed`: the agent's turn settled. Consume the optional `result`: the final assistant message.
+- `completed`: the agent's turn settled, after any [tasks](/docs/tools/workflows#run-calls-as-tasks-task) it started finished. Consume the optional `result`: the final assistant message.
 - `failed`: inspect the structured `error`.
 - `cancelled`: cancellation reached a terminal state.
 

package/docs/channels/overview.mdx

@@ -3,15 +3,23 @@ title: "Overview"
 description: "How users reach your agent: the channel contract, the base eve HTTP channel, and authoring custom channels."
 ---
 
-A channel is the edge adapter between a platform and your agent. It does three things:
+A channel connects a platform to your agent. For conversations, it:
 
-- Normalizes platform input into a user message.
-- Owns the channel-local address that maps a platform conversation to its current durable session.
-- Decides delivery, meaning how, where, and whether a response goes back.
+- Converts incoming messages into agent input.
+- Maps each platform conversation to an eve session.
+- Decides how, where, and whether to deliver replies.
+
+A channel can also receive events and pass them to another channel, without starting a conversation of its own.
 
 eve ships a base HTTP channel plus first-class platform channels, and you can author your own. Browse the full set in the [Integrations](/integrations) gallery and choose the Channels filter.
 
-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.
+After a channel dispatches a message, eve runs the same agent runtime regardless of where the event came from. Tools and instructions do not need channel-specific logic.
+
+## Choose where the conversation lives
+
+The agent doesn't have to reply where an event arrived. A webhook, for example, can start a conversation in a team chat without sending an agent reply to the webhook's source.
+
+Use a [cross-channel hand-off](./custom#cross-channel-hand-off) when the conversation belongs elsewhere. The destination channel handles the session, replies, and follow-up messages. To post a notification without running the agent, use the platform's API instead.
 
 ## Audience
 
@@ -72,57 +80,7 @@ The eve channel is the framework's default HTTP session API, the routes the term
 
 ## Custom channels
 
-When eve doesn't ship a channel for your surface, build one with `defineChannel` from `eve/channels`. A custom channel declares route handlers (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `WS`), an `events` map, and uses `send(address, input)` to start or resume a session. See [Custom channels](./custom) for the full walkthrough, including WebSocket routes, cross-channel agent hand-off, channel metadata, address tokens, and file uploads.
-
-A cross-channel `send(...)` supplies input to the agent and invokes the model on the destination channel. eve does not currently provide a direct cross-channel provider-message queue. To post without starting a turn, use the provider API. See [Durable cross-channel notifications](../patterns/durable-cross-channel-notifications) when delivery also needs application-managed retries and deduplication.
-
-## Background task results
-
-Pass `taskDeliveryPolicy` to `send(...)` to choose how the session reports background results:
-
-- `"auto"` (default for new channel sessions): ready results can invoke the parent while other tasks continue. The parent reports results that are useful independently and stays silent when a useful answer needs unfinished work.
-- `"cohort"`: wait for overlapping tasks to settle, then deliver their terminal outcomes together.
-
-```ts title="agent/channels/reports.ts"
-import { defineChannel, POST } from "eve/channels";
-import { localDev, routeAuth } from "eve/channels/auth";
-
-export default defineChannel({
-  routes: [
-    POST("/reports", async (request, { from }) => {
-      const auth = await routeAuth(request, localDev());
-      if (auth instanceof Response) return auth;
-      const session = await from("daily-report").send("Prepare the daily reports.", {
-        auth,
-        taskDeliveryPolicy: "cohort",
-      });
-      return Response.json({ sessionId: session.id });
-    }),
-  ],
-});
-```
-
-The option is available on channel-local `from(...).send(...)`, cross-channel
-`to(...).send(...)`, fixed-session `send(...)`, Chat SDK `bridge.send(...)`, and client
-sends. An explicit value
-updates the session's policy, including pending background tasks; later sends that
-omit it preserve that policy. A cross-channel send carries its setting through the
-receiver's `from(...).send(...)` unless that call supplies an explicit value.
-
-[Schedules](../schedules#background-task-results) default new sessions to `"cohort"`.
-A schedule handler can pass `taskDeliveryPolicy: "auto"` to `send(...)` to override
-that default. Child sessions use their own policy.
-
-With `"auto"`, a model call may finish without a user-visible message. Results
-already queued from the same cohort may share a turn. Each reporting turn receives
-the whole cohort, including pending tasks and available outputs, so previously
-withheld results remain available for a later combined report.
-
-Input requests and explicit task messages remain eligible for delivery under
-either policy. Failure and cancellation update task state immediately; their
-automatic reports follow the selected policy. User messages follow `turnPolicy`.
-See [Completion batching](../subagents#completion-batching) for cohort membership
-and result ordering.
+Build a channel with `defineChannel` from `eve/channels` when you need your own HTTP or WebSocket endpoint. Its routes can start conversations on that channel or hand work to another one. See [Custom channels](./custom) for examples and the authoring API.
 
 ## Relationship to the Chat SDK
 

package/docs/channels/slack.mdx

@@ -152,7 +152,7 @@ controls observability content capture, not access to the channel. See
 Message hooks return `{ auth }` to dispatch, `null` to drop, or `{ auth, context }` to inject background into history. Public conversations use the returned `title`, or the triggering message text when `title` is omitted. DMs and private channels always use `Private message` so the run title does not expose message details.
 
 - `onMessage(ctx, message)` handles Slack `message` events. eve drops messages authored by the installed app before this hook runs, preventing self-reply loops. Messages from other bots remain visible; check `message.author?.isBot` when those should also be ignored. `ctx.isBotMentioned()` and `ctx.isSubscribed()` support mention and active-thread policies.
-- `onAppMention(ctx, message)` handles only `app_mention` and takes precedence over `onMessage`. Its default derives workspace-scoped auth and posts `Thinking…`.
+- `onAppMention(ctx, message)` handles only `app_mention` and takes precedence over `onMessage`. Its default derives workspace-scoped auth.
 - `onDirectMessage(ctx, message)` handles only DMs and takes precedence over `onMessage`. Bot-authored messages and edits are filtered first; Slack requires `message.im` and `im:history`.
 
 | Incoming event         | Handler order                                                       |
@@ -164,6 +164,8 @@ Message hooks return `{ auth }` to dispatch, `null` to drop, or `{ auth, context
 
 Only the first available handler runs. A message hook returning `null` drops the message; it does not continue down the table.
 
+Message hooks only decide whether and how a message starts a turn. They don't render anything, so replacing one never changes what people see: eve still acknowledges the message, shows progress, and posts the reply. To change what the agent posts, add [renderers](#customize-rendering).
+
 `onInteraction(action, ctx)` separately handles user-owned `block_actions` callbacks. eve-owned HITL buttons and modal submissions go through `onInputResponse(ctx, submission)` instead. eve attaches the triggering Slack user id to the same model message as its text, preserving speaker attribution without profile lookups.
 
 Use `onShortcut(shortcut, ctx)` for message shortcuts and global shortcuts configured under **Interactivity & Shortcuts** in your Slack app. The handler receives the shortcut callback ID, user, workspace, and trigger ID. Message shortcuts also include the selected message and channel. The context exposes workspace-scoped Slack API access because global shortcuts have no channel or message. eve acknowledges shortcut requests immediately and keeps their handlers alive in the background.
@@ -397,7 +399,7 @@ const session = await ctx.resolveSession({ target });
 
 ### Slack API calls outside a handler
 
-Inside inbound webhook handlers such as `onAppMention`, `onEvent`, `onInteraction`, `onShortcut`, `onSlashCommand`, and `onInputResponse`, `ctx.slack.request(operation, body)` is the raw-API escape hatch. Inside an `events` handler, use `channel.slack.request(...)` instead. Outside those contexts there is no handle — a schedule resolving reactions on old
+Inside inbound webhook handlers such as `onAppMention`, `onEvent`, `onInteraction`, `onShortcut`, `onSlashCommand`, and `onInputResponse`, `ctx.slack.request(operation, body)` is the raw-API escape hatch. Inside a [renderer](#customize-rendering)'s event handler, use `channel.slack.request(...)` instead. Outside those contexts there is no handle — a schedule resolving reactions on old
 messages, for example, has no inbound Slack request. For that, call the
 same primitive the handle uses directly:
 
@@ -450,27 +452,179 @@ The bases say where a call may go. `apiBaseUrl` is the base Slack Web API method
 
 ### Delivery
 
-The default handlers reply in-thread and show activity. Typing indicators post automatically: `Thinking…` on inbound, `Working…` on `turn.started`, a truncated reasoning snippet on `reasoning.appended`, and an action label on `actions.requested` — the tool name plus its most telling argument (`grep useEveAgent`, `read_file agent/agent.ts`), the subagent or remote-agent name for dispatched calls, and `+N more` when the model requests several actions at once. The model's own pre-tool narration, when present, takes precedence over the derived label. 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 an inbound handler or the `events` handlers to customize.
+eve shows an agent's progress in two places. Short work, such as thinking or a tool call, appears in the thread status and never posts a message. [Tasks](/docs/tools/tasks), which keep working while the conversation continues, appear in a task card: one message per turn that eve updates in place. Replies post as ordinary messages, so the thread holds the conversation, the task card, and nothing else.
+
+| Moment                             | Thread status                                                                   |
+| ---------------------------------- | ------------------------------------------------------------------------------- |
+| A mention or DM arrives            | `Thinking...`, right away, while the message hook is still deciding             |
+| The message hook drops the message | Cleared                                                                         |
+| The turn starts                    | `Working...`                                                                    |
+| The model reasons                  | The first line of its reasoning                                                 |
+| The model calls tools              | Its narration before the calls, or an action label such as `Search useEveAgent` |
+| The turn waits on its tasks        | `Waiting on researcher...`, or `Waiting on 3 tasks...`                          |
+| A reply posts                      | Cleared by Slack                                                                |
+
+Slack clears a thread status after two minutes without a message, so during a long wait the task card is what shows the work is still going.
+
+Action labels follow the same rule as the task card titles described below, plus `+N more` when the model requests several actions at once. They leave out the model's own `task_wait` and `task_cancel` calls. Reasoning snippets build progressively: extensions of at least four characters appear immediately, while smaller streamed deltas use a five-second refresh interval to avoid one Slack request per token.
+
+Replies up to 12,000 characters render inline. Longer replies are uploaded unchanged as a Markdown snippet named `eve-response.md` with a short in-thread note, which requires the `files:write` bot scope. Upload failures are logged by the channel dispatcher; they do not trigger a model retry.
 
-The built-in `message.completed` handler renders responses up to 12,000 characters inline. Longer responses are uploaded unchanged as a Markdown snippet named `eve-response.md` with a short in-thread note, which requires the `files:write` bot scope. Upload failures are logged by the channel dispatcher; they do not trigger a model retry. An authored `events["message.completed"]` handler replaces this behavior and owns its own delivery limits.
+When the model replies while its tasks keep working, that reply posts like any other, and the reply after the results posts as another message. A schedule's session posts only the final reply.
 
 Outbound text preserves bare `@` tokens as literal text. To mention a user, embed Slack's `<@USER_ID>` syntax directly or use `channel.thread.mentionUser(userId)`.
 
-When a session starts without a `threadTs` (say, from a schedule's `to(slack, target).send(...)`), eve gives it a unique temporary continuation token. The first agent post anchors the session to the Slack message timestamp, and later posts and mentions resume that same session. Pass `initialMessage` with a `Card` to land a structured anchor first instead. `threadTs` and `initialMessage` are mutually exclusive.
+### Task card
 
-The example below overrides `onAppMention` to gate on an authored message. The built-in completion handler still posts the reply and uploads long responses as snippets. Event handlers receive `(eventData, channel, ctx)`, with Slack platform handles on `channel.thread` and `channel.slack`:
+When a turn starts its first task, eve posts a task card in the thread and keeps it current until the turn and its tasks finish. One task renders as a Slack `task_card` block; two or more render as a `plan` block with one row per task the turn started. What an agent task does on its own, including the tasks it starts, stays inside that task and does not add rows. The card needs no configuration beyond the `chat:write` scope the channel already uses.
 
-```ts
-import { defaultSlackAuth, slackChannel } from "eve/channels/slack";
+Each row shows:
+
+- **Title:** the tool's [`label.start`](/docs/tools#label-tool-activity), or the tool name. An agent task shows the agent name and the first sentence of its brief (`researcher: Find the incidents behind the checkout spike`). A task the agent hands to its own copy shows the brief alone.
+- **Waiting:** while the task waits on an approval, an answer, or a sign-in, the row says so, as in `Waiting for approval`. In a DM or private channel it also shows the request's prompt; elsewhere it shows only what kind of request is waiting, since `approvalChannel` can send the request to one person. The request itself posts wherever `approvalChannel` sends it, and the row goes back to working once the request resolves.
+- **How it ended:** the first sentence of the result or the agent's reply, cut to about 100 characters, `Failed` for a failure, or a line for a cancelled task that says why it stopped. A task the model cancelled with `task_cancel` shows `Stopped early since it was no longer needed` with a success check, since the model no longer needed that work. A task stopped by [cancelling the turn](#message-hooks) shows `Stopped by request`, one stopped because its turn ended shows `Stopped when the turn ended`, and one whose run stopped on its own shows `Stopped`. Those rows and failed rows never show a success check. In a DM or private channel, a failure also shows the first sentence of its error, as in `Failed: Rate limited`. Error text can carry internal details, so everywhere else, including proactive sessions without a known `audience`, shows `Failed` alone. A completed or failed task that ran for a second or more also shows how long it took: `Done in 1m 14s: Found three incidents.` or `Failed after 3m`.
+
+The plan title summarizes the turn: `Working on 2 tasks`, `1 of 2 tasks done`, `Waiting for approval`, then `Finished 2 tasks in 3m` or `Finished 3 tasks in 5m 12s: 1 failed, 1 stopped`. When every task calls a declared subagent or remote agent, and the turn calls three or fewer of them, the title names them instead of counting: `Asking researcher and reviewer`, then `Waiting on reviewer · 1 of 2 tasks done`. Tasks the model cancelled with `task_cancel` count as finished, not stopped. A resumable task continued in a later turn appears in that turn's card.
+
+A turn stays open while its tasks work, so messages you send during that time continue the same turn. When that turn starts a task after every task on its card has settled, eve marks that card finished and posts a new card for the new work, so the new tasks don't update a card further up the thread.
+
+eve writes the card from the session's own events as they happen, and only when it changed. A failed Slack call never fails the turn: eve tries a failed write once more after a second, then again on the turn's next change. If someone deletes the card, eve posts it again on its next change. Card posts never unfurl links. Schedule sessions and sessions without a Slack thread get no card.
+
+### Customize rendering
+
+Without `renderers`, eve renders everything above with its default renderer. Pass `renderers` to change what the agent posts without replacing that default. Each renderer wraps the ones after it, ending with eve's default renderer, and has three optional parts:
+
+- `received(message, channel, next)` acknowledges a mention or DM the moment it arrives, and another channel message once `onMessage` dispatches it. eve's default sets `Thinking...`.
+- `events` handles session events such as `message.completed` or `input.requested`. Each handler receives `(eventData, channel, ctx, next)`, with Slack platform handles on `channel.thread` and `channel.slack`; a `session.failed` handler receives `(eventData, channel, next)`.
+- `taskCard(view, next)` returns the task card's blocks and notification text, or `null` for no card.
+
+Call `next()` to run the rest of the chain, ending with eve's default. Call it after your own work, before it, or with changed data, as in `next({ ...event, message })`; the rest of the chain runs at most once. Skip `next` to replace the default for that event. This renderer adds feedback buttons below each final reply and a context row to the finished task card:
+
+```ts title="agent/channels/slack.ts"
 import { connectSlackCredentials } from "@vercel/connect/eve";
+import { defineSlackRenderer, slackChannel } from "eve/channels/slack";
+
+const feedback = defineSlackRenderer({
+  events: {
+    async "message.completed"(event, channel, _ctx, next) {
+      await next(); // eve posts the reply, or uploads a long one as a snippet
+      if (event.finishReason === "tool-calls") return;
+      await channel.thread.post({
+        blocks: [
+          {
+            type: "context_actions",
+            elements: [
+              {
+                type: "feedback_buttons",
+                action_id: "reply_feedback",
+                positive_button: { text: { type: "plain_text", text: "Helpful" }, value: "up" },
+                negative_button: {
+                  text: { type: "plain_text", text: "Not helpful" },
+                  value: "down",
+                },
+              },
+            ],
+          },
+        ],
+        text: "Was this helpful?",
+      });
+    },
+  },
+  taskCard(view, next) {
+    const card = next(view);
+    if (card === null || view.state !== "finished") return card;
+    const note = {
+      type: "context",
+      elements: [{ type: "mrkdwn", text: "Results are in the reply below." }],
+    };
+    return { ...card, blocks: [...card.blocks, note] };
+  },
+});
 
 export default slackChannel({
   credentials: connectSlackCredentials("slack/my-agent"),
-  onAppMention: (ctx, message) =>
-    message.author ? { auth: defaultSlackAuth(message, ctx) } : null,
+  renderers: [feedback],
+});
+```
+
+`taskCard` runs for every turn that calls a tool, and receives the same view eve's default renders from:
+
+- `state`: `blocked` while any task waits on a person, `working` while the turn or any other task works, then `finished`.
+- `tasks`: the tasks the turn started, each with a `title`, `status`, `blockedOn`, and `summary`. A failed task's `summary` and a blocked task's `blockedOn.label` are present only in a DM or private channel.
+- `actions`: the turn's other tool calls, each with its tool `name`, `title`, `status`, and `input`. `input` is left out when its JSON is longer than 4,096 characters.
+
+`taskCard` is synchronous and pure: eve posts the card and updates it as the view changes. eve's default returns `null` for a turn that started no tasks. Its block keeps the same `block_id` for the whole turn; keep that `block_id` on a block you build in its place. To change a row's title in every channel, give the tool a [label](/docs/tools#label-tool-activity) instead.
+
+Renderers run in the order you list them, and the first one is outermost. `onInteraction` receives clicks on buttons a renderer posts, such as the feedback buttons above.
+
+### Show your own tool on the task card
+
+A renderer can draw any of the turn's tool calls from their input. For example, give the agent a `plan` tool that records a checklist, and show the checklist ahead of eve's task rows:
+
+```ts title="agent/tools/plan.ts"
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description:
+    "Show the steps of a multi-step request as a checklist. Pass the complete list on every call.",
+  inputSchema: z.object({
+    items: z.array(
+      z.object({
+        status: z.enum(["pending", "working", "completed", "failed"]),
+        title: z.string(),
+      }),
+    ),
+  }),
+  async execute() {
+    return { updated: true };
+  },
 });
 ```
 
+```ts title="agent/channels/slack.ts"
+import { type BlockKitBlock, defineSlackRenderer, slackChannel } from "eve/channels/slack";
+
+interface PlanItem {
+  readonly status: "pending" | "working" | "completed" | "failed";
+  readonly title: string;
+}
+
+const SLACK_STATUS = {
+  completed: "complete",
+  failed: "error",
+  pending: "pending",
+  working: "in_progress",
+} as const;
+
+const plan = defineSlackRenderer({
+  taskCard(view, next) {
+    const card = next(view);
+    const calls = view.actions.filter((action) => action.name === "plan");
+    const items = calls.at(-1)?.input?.items as PlanItem[] | undefined;
+    if (items === undefined) return card;
+    // eve's card is one `plan` block, or one `task_card` block for a single task.
+    const [block] = card?.blocks ?? [];
+    const taskRows: BlockKitBlock[] =
+      block === undefined ? [] : block.type === "plan" ? (block.tasks as BlockKitBlock[]) : [block];
+    const planRows = items.map((item, index) => ({
+      status: SLACK_STATUS[item.status],
+      task_id: `plan_${index}`,
+      title: item.title,
+    }));
+    const tasks = [...planRows, ...taskRows.map(({ type: _type, ...row }) => row)];
+    return {
+      blocks: [{ type: "plan", block_id: block?.block_id, title: "Plan", tasks }],
+      text: `Plan: ${items.map((item) => item.title).join(", ")}`,
+    };
+  },
+});
+
+export default slackChannel({ renderers: [plan] });
+```
+
+A turn that only plans gets a card too, because `taskCard` runs for every turn that calls a tool.
+
 ### Human-in-the-loop (HITL)
 
 HITL renders as Slack buttons and selects. Fixed-choice actions and freeform modal submissions pass through `onInputResponse` before the parked session resumes. The initial **Type your answer** action only opens eve's modal; the hook runs when the user submits an answer.
@@ -490,7 +644,7 @@ export default slackChannel({
 
 The callback receives the `InputRequest` and current `SessionContext`, so it can switch on `kind`, `action`, or presentation properties. Omit it to keep every request in the thread, or return `"direct-message"` unconditionally to make every request private. If eve cannot resolve the triggering Slack user for a direct message, it logs the undelivered request and posts no fallback, so private delivery fails closed. The existing `onInputResponse` or tool approval response policy still decides whether the person who clicks may respond.
 
-An authored `input.requested` handler can extend delivery and then hand the requests back to eve through `defaultDeliver()`. For example, an application can add non-sensitive context to the Slack thread before eve renders the actionable controls. The configured `approvalChannel` still sends sensitive reviews to a DM and keeps ordinary requests in the thread:
+A renderer's `input.requested` handler can extend delivery and then hand the requests on to eve with `next()`. For example, an application can add non-sensitive context to the Slack thread before eve renders the actionable controls. The configured `approvalChannel` still sends sensitive reviews to a DM and keeps ordinary requests in the thread:
 
 ```ts title="agent/channels/slack.ts"
 import { slackChannel } from "eve/channels/slack";
@@ -500,47 +654,88 @@ export default slackChannel({
   approvalChannel(request) {
     return isPrivate(request) ? "direct-message" : "thread";
   },
-  events: {
-    async "input.requested"(event, channel, _ctx, defaultDeliver) {
-      await channel.thread.post({
-        blocks: [
-          {
-            type: "context",
-            elements: [
+  renderers: [
+    {
+      events: {
+        async "input.requested"(_event, channel, _ctx, next) {
+          await channel.thread.post({
+            blocks: [
               {
-                type: "mrkdwn",
-                text: "A review is needed before this work can continue.",
+                type: "context",
+                elements: [
+                  {
+                    type: "mrkdwn",
+                    text: "A review is needed before this work can continue.",
+                  },
+                ],
               },
             ],
-          },
-        ],
-        text: "A review is needed before this work can continue.",
-      });
-      await defaultDeliver(event);
+            text: "A review is needed before this work can continue.",
+          });
+          await next();
+        },
+      },
     },
-  },
+  ],
 });
 ```
 
-Authorization prompts split public status from private credentials. A sign-in challenge (OAuth URL, device code) is a credential. Anyone who completes it binds their identity to the session's connection. The default `authorization.required` handler posts a public, link-free status in the thread, delivers the actual challenge ephemerally to the triggering user, device code included, and then updates that public status when `authorization.completed` fires. The handler receives a private-delivery context with `postEphemeral`, `postDirectMessage` (needs the `im:write` scope), and `state`. There is, intentionally, no public `post` and no raw API access.
+#### Render and decode HITL controls yourself
+
+`eve/channels/slack` exports the helpers eve uses for its own HITL controls. `renderInputRequestBlocks(request, route?)` returns the Block Kit blocks for one `InputRequest`. `deriveHitlResponse(action)` decodes a click on those blocks into `{ response, kind?, route? }`, where `response` is the eve `InputResponse`, or returns `null` for any other action. Every eve-owned control's `action_id` starts with `HITL_ACTION_PREFIX` (`"eve_input:"`), so give your own buttons a different prefix to keep them routed to `onInteraction`.
+
+```ts
+import { deriveHitlResponse, renderInputRequestBlocks } from "eve/channels/slack";
+
+const [card] = renderInputRequestBlocks(request) as [
+  { actions: { action_id: string; value: string }[] },
+];
+const button = card.actions[0]!;
+
+// For a request whose first option id is "approve":
+deriveHitlResponse({ actionId: button.action_id, value: button.value });
+// { response: { optionId: "approve", requestId: request.requestId } }
+```
+
+Use them to test a custom renderer against eve's wire format, or to post eve's controls from your own renderer. A click on these controls in the session's Slack thread resumes the session through `onInputResponse`, the same as eve's own controls. To pass `response` to `respond()` yourself, validate it first with `parseInputResponses` from `eve/client`.
+
+Authorization prompts split public status from private credentials. A sign-in challenge (OAuth URL, device code) is a credential. Anyone who completes it binds their identity to the session's connection. The default `authorization.required` handler posts a public, link-free status in the thread, delivers the actual challenge ephemerally to the Slack user behind the event's `principalId`, device code included, and then updates that public status when `authorization.completed` fires. A renderer's `authorization.required` handler receives a private-delivery context with `postEphemeral`, `postDirectMessage` (needs the `im:write` scope), and `state`. There is, intentionally, no public `post` and no raw API access. Its `next()` reaches eve's default, which posts the public status; skip `next` to deliver the challenge yourself, as this handler does by direct message. `state.slackUsersByPrincipal` maps each principal eve has seen in the thread, through a message or an input response, to its Slack user ID. If the principal has no entry, the challenge is not sent privately.
 
 ```ts
-events: {
-  "authorization.required"(eventData, channel) {
-    const userId = channel.state.triggeringUserId;
-    if (!userId || !eventData.authorization?.url) return;
-    return channel.postDirectMessage(userId, `Sign in to continue: ${eventData.authorization.url}`);
+renderers: [
+  {
+    events: {
+      "authorization.required"(eventData, channel) {
+        const userId =
+          eventData.principalId === undefined
+            ? undefined
+            : channel.state.slackUsersByPrincipal?.[eventData.principalId];
+        if (!userId || !eventData.authorization?.url) return;
+        return channel.postDirectMessage(userId, `Sign in to continue: ${eventData.authorization.url}`);
+      },
+    },
   },
-},
+],
 ```
 
 The private authorization button uses the label **Sign in**, so long connection display names do not make the button invalid. The public status identifies the connection.
 
 ### Proactive sessions
 
-Start a session without an inbound message through `ctx.to(slack, target).send(message, { auth })` from another channel, or `to(slack, target).send(message, { auth })` from a schedule `run` handler. The proactive target shape is `{ channelId, installationTeamId?, threadTs?, initialMessage?, audience? }`. It defaults to `unknown`; pass `audience` only when the caller already knows the destination's visibility. Set `installationTeamId` to the app installation workspace when a function-form bot token must select an installation. This sends turn input to the agent; it is not a direct Slack post.
+Start a Slack conversation from a [webhook on another channel](./custom#cross-channel-hand-off) or a [schedule](../schedules#handler-form-run), without waiting for someone to message the app.
+
+Pass `{ channelId }` as the target to start a new thread. The agent's first post becomes the thread's root message. You can also set these target fields:
+
+| Field                | Use                                                                                       |
+| -------------------- | ----------------------------------------------------------------------------------------- |
+| `threadTs`           | Continue an existing thread instead of creating one.                                      |
+| `initialMessage`     | Post a card as the thread root before the agent runs. Cannot be combined with `threadTs`. |
+| `installationTeamId` | Select the app installation workspace when using a function-form bot token.               |
+| `audience`           | Set the destination's visibility when you know it. Defaults to `unknown`.                 |
+
+The default mention handler lets teammates continue the session by mentioning the app in the thread. To accept replies without a mention, [configure an `onMessage` hook and the required Slack subscriptions and scopes](#continue-conversations-without-repeated-mentions).
 
-To post without invoking the model, use `ctx.thread.post(...)` in an inbound Slack handler or `channel.thread.post(...)` in an `events` handler. Use `callSlackApi(...)` where no Slack channel context exists. For application-managed retries and deduplication, see [Durable cross-channel notifications](../patterns/durable-cross-channel-notifications).
+For a Slack post without an agent turn, use `ctx.thread.post(...)` in an inbound handler or `channel.thread.post(...)` in a renderer's event handler. Outside a handler, use [`callSlackApi(...)`](#slack-api-calls-outside-a-handler).
 
 ### Attachments