The Open Framework for Building Agents
title: "Hooks" description: "Subscribe to runtime stream events from agent/hooks/."
Hooks are eve's authored extension points for the runtime event stream. A hook subscribes to stream events and runs side effects after each event is durably recorded, such as audit logging, metrics and alerting, or persisting every session and message to your own database for analytics. Reach for one to observe what the agent does without writing a tool, a context provider (a value made available across a step), or a channel adapter handler (a handler defined on a channel's adapter; see Channels).
Define a hook
import { defineHook } from "eve/hooks";
export default defineHook({
events: {
async "session.started"(_event, ctx) {
console.info("session started", { sessionId: ctx.session.id });
},
async "message.completed"(event) {
console.info("model finished", { length: event.data.message?.length ?? 0 });
},
},
});
The slug is the path-relative basename. agent/hooks/audit.ts becomes "audit", and agent/hooks/auth/load-profile.ts becomes "auth/load-profile".
defineHook, HookDefinition, and HookContext live on eve/hooks.
A hook file declares stream-event subscribers under the events map, keyed by event type, with * matching every event. Subscribe to any event in the runtime stream vocabulary documented in Sessions, runs and streaming, including the lifecycle events session.started, turn.completed, message.completed, action.partial, and action.result. Handlers are observe-only. They cannot inject model context. To contribute runtime model messages, use defineDynamic and defineInstructions in agent/instructions/.
Scope side effects to a channel
A hook under agent/hooks/ observes matching events from every channel on the root agent. defineHook has no channel filter. Use a channel's events configuration when a handler assumes a specific platform or should run only for sessions owned by that channel:
import { githubChannel } from "eve/channels/github";
export default githubChannel({
events: {
async "turn.completed"(event, channel, ctx) {
console.info("GitHub turn completed", {
repository: channel.repository.fullName,
sessionId: ctx.session.id,
turnId: event.turnId,
});
},
},
});
A GitHub channel event handler cannot fire for a Slack-owned session, so platform-specific side effects do not depend on an early-return guard. On a built-in channel, an authored handler replaces that channel's default handler for the same event key. Check the channel page before overriding events that deliver replies, progress, errors, or human-input prompts. The Slack channel takes renderers instead: a renderer's handler keeps Slack's default by calling next() and replaces it by skipping next.
Use ctx.channel.kind inside a global hook only when the operation is otherwise agent-wide and conditional handling is intentional. For a channel with event handlers, such as githubChannel, slackChannel, and the other built-ins, the kind is the path-derived identity. agent/channels/github.ts reports channel:github, so ctx.channel.kind === "github" never matches. Import the channel definition and compare it with isChannel from eve/channels:
import { isChannel } from "eve/channels";
import { defineHook } from "eve/hooks";
import github from "../channels/github";
export default defineHook({
events: {
async "turn.started"(_event, ctx) {
if (!isChannel(ctx.channel, github)) return;
// GitHub-owned turns only.
},
},
});
A route-only defineChannel with no event handlers keeps the kind "http", so isChannel does not match it in a hook. Compare ctx.channel.kind === "http" for those channels instead.
For typed channel metadata in dynamic resolvers or instrumentation, narrow with isChannel the same way; see OpenTelemetry runtime context.
Hook structure and context
Every handler receives the same HookContext, including the shared session
helpers documented in Session context:
interface HookContext extends SessionContext {
readonly agent: { readonly name: string; readonly nodeId?: string };
readonly channel: { readonly kind?: string; readonly continuationToken?: string };
cancel(): void;
}
That means a hook can access the current sandbox and release its backing compute at an application-defined boundary:
import { defineHook } from "eve/hooks";
export default defineHook({
events: {
async "turn.completed"(_event, ctx) {
const sandbox = await ctx.getSandbox();
await sandbox.stop();
},
},
});
Every built-in backend stops its underlying compute while preserving the durable session and filesystem for the next callback. On Vercel, the current handle can also automatically resume on later I/O. A hook failure, including a failed stop, follows the normal hook failure behavior.
For task.started, task.settled, and agent.started, ctx.session.id
identifies the session that started the task or opened the subagent session.
Typed handlers and * handlers receive this context even when the event
arrives between turns. These hooks can use ctx.getSandbox() against that
session. Session state and sandbox changes they make are kept for the
session's next turn. agent.started appears when the child session opens, or
when the parent's current model step ends if one is running.
Narrowing tool results
toolResultFrom narrows an action.result event to a specific authored tool or connection (MCP or OpenAPI) and returns typed output. Import it from eve/tools:
import { defineHook } from "eve/hooks";
import { toolResultFrom } from "eve/tools";
import getWeather from "../tools/get-weather";
import linear from "../connections/linear";
export default defineHook({
events: {
"action.result"(event) {
// Authored tool: output is typed as the tool's return type
const weather = toolResultFrom(event.data.result, getWeather);
if (weather) {
console.log(weather.output.temperature);
}
// Connection: output is unknown, toolName is qualified
const linearResult = toolResultFrom(event.data.result, linear);
if (linearResult) {
console.log(linearResult.connectionToolName, linearResult.output);
}
},
},
});
Returns undefined when the result doesn't match, or when isError is true. For authored tools the return includes { output, toolName, callId } with output typed as the tool's TOutput. For connections it includes { output, toolName, connectionToolName, callId } with output as unknown.
This works for a mounted extension's tools too — import the tool from the extension's ./tools export and pass it. toolResultFrom matches the namespaced result (crm__search) because it keys off the tool definition, not the name:
import { search } from "@acme/crm/tools";
// inside "action.result":
const crmSearch = toolResultFrom(event.data.result, search); // typed; matches crm__search
When one definition is mounted under more than one tool name, for example when a subagent re-exports an extension tool, toolResultFrom matches results from every mounted name.
Persist events to your own database
Every event carries a meta envelope with meta.id, a unique, sortable identifier for that event. It makes a natural primary key for an events table:
import { defineHook } from "eve/hooks";
export default defineHook({
events: {
async "*"(event, ctx) {
await db.query(
`insert into agent_events (id, session_id, type, data, emitted_at)
values ($1, $2, $3, $4, $5)
on conflict (id) do nothing`,
[
event.meta.id,
ctx.session.id,
event.type,
"data" in event ? event.data : null,
event.meta.at,
],
);
},
},
});
meta.id is stable for the life of the persisted event, so a consumer that re-reads the stream can ingest the same event twice safely. It is not a retry guard for the hook itself: if a step is interrupted and re-runs, the turn re-emits its events as new events with new ids, and your hook runs again for each one.
What to key on instead depends on what you are protecting:
- A side effect that must happen once per turn or step — a charge, an email, a ticket — keys well on the coordinates in
event.data(turnId,stepIndex,sequence). A retry restores those from the step's input, so the second attempt computes the same key and your gate holds. - Stored content should not key on those coordinates. The retry re-invokes the model, so one coordinate can carry different text on each attempt.
on conflict (turn_id, step_index, sequence) do nothingwould keep the abandoned attempt and drop the one that finished. Key onmeta.id, and accept that an interrupted turn leaves both attempts in the table.
Behind that split is an asymmetry worth knowing: durable history keeps only the attempt that completed, while the event stream keeps every attempt, and no field marks which is which. Hooks are at-least-once, and no key collapses a retry.
See the event envelope for the full contract.
Execution order
When a session publishes a stream event while it runs, the step that owns the session does four things in order:
- Channel delivery. The channel adapter handler runs.
- Write. The event is stamped with its
metaenvelope, then written to the durable stream. - Hooks. Stream-event hooks fire (typed handlers first, then the
*wildcard). Return values are ignored. - Model preparation, for model lifecycle events. Dynamic resolvers subscribed to those events update the model context. Subagent notifications do not run model preparation.
Hooks always run after the event is durably recorded, so if a hook throws, the stream stays consistent. The persisted event and every hook observe the same meta.id.
What happens when a hook throws
eve logs a thrown or rejected handler with the hook slug, subscription, event type, event ID, and session ID, then runs the remaining subscribers in order. The current turn, subagent notification, and session continue. This applies to every stream-event hook, including turn.started, step.started, and failure events. Throwing from a hook does not reject work or veto a turn. To stop the running turn, call ctx.cancel().
A hook failure does not trigger a retry. State changes and external side effects made before the exception are not rolled back. If a side effect needs retries or compensation, handle that inside the hook. Runtime failures outside the authored handler, such as failures setting up context or persisting state, still propagate. If persisting state after a task.started, task.settled, or agent.started event fails, the workflow runtime retries the publishing step, which can publish the event again.
Cancel the running turn from a hook
Call ctx.cancel() when a hook finds that the turn cannot proceed. For example, a turn.started hook that cannot load the caller's credentials can stop the turn before the model runs, instead of letting every tool call fail:
import { defineHook } from "eve/hooks";
import { loadWorkspaceCredentials } from "../lib/credentials";
export default defineHook({
events: {
async "turn.started"(_event, ctx) {
try {
await loadWorkspaceCredentials(ctx.session.auth.current);
} catch (error) {
console.warn("cancelling turn: workspace credentials unavailable", {
error,
sessionId: ctx.session.id,
});
ctx.cancel();
}
},
},
});
The remaining subscribers for the event still run. Then eve cancels the turn the same way session.cancel() does: in-flight model and tool work is aborted, delegated child turns are cancelled, and the turn ends with turn.cancelled followed by session.waiting. No failure event is emitted. A cancel from turn.started or step.started takes effect before that model call. In a conversation, the next message starts a new turn. A delegated task reports the cancellation to its caller.
A plain-text message that answers a pending question, such as one from ask_question, is recorded as message.received before eve delivers it. Calling ctx.cancel() from that event's hook cancels the turn instead: the question resolves as cancelled, and the waiting tool call never receives the text.
The same goes for the action.partial a workflow tool reports while the turn waits on it: ctx.cancel() from its hook cancels the turn, and the run's result never reaches the model.
ctx.cancel() returns void rather than a promise. The turn stops after the hook returns, so there is nothing to await. Call it before the handler's promise settles: eve ignores a call from work the handler does not await and logs a warning.
ctx.cancel() only stops a running turn. eve logs a warning and ignores the call on step.failed, turn.completed, turn.failed, turn.cancelled, turn.waiting, session.waiting, session.completed, session.failed, context.cleared, task.started, task.settled, and agent.started, and during clear or compact requests.
Subagent isolation
Subagents may carry their own agent/hooks/ directory. Subagent hooks fire only inside the subagent scope. Parent-agent hooks do not fire for subagent turns, and subagent hooks see only the subagent's own context.
Interactive events such as input.requested and authorization.required are also published on the parent stream. Parent hooks observe these events after the parent channel handler and stream write, with the parent's session, agent, and channel context. The event retains the child's turn coordinates, so event.data.turnId can differ from ctx.session.turn.id. A proxied input.requested also carries event.data.callId, the parent call that waits on it. The parent follows a proxied input.requested or authorization.required with turn.waiting for its own open turn, which stays open until the running call finishes. A proxied authorization.completed is not followed by a parent turn event. These parent events also invoke parent hooks; they do not resolve pending input requests.
Hook vs tool vs provider
| Need | Use |
|---|---|
| Observe runtime events (audit, metrics, alerting) | events.<type> (or a channel adapter handler) |
| Provide structured input to the model on demand | a tool |
| Make a value available across the entire step | a context provider |
| Subscribe to platform-specific events | a channel adapter handler |
Stream-event hooks and channel adapter event handlers are structurally identical. Choose the channel adapter handler when you are authoring adapter-specific behavior, and choose events.* when you are authoring agent-level behavior that should fire across every channel. Both fire when both are registered.