Hooks

A hook subscribes to selected session events and can run a side effect after each matching event is recorded. Hooks run in the serving process for every session of the agent. They cannot change the turn, the prompt, or the reply. A handler that throws is logged and skipped.

Treat the event as read-only. Later subscribers see the same object. A hook is the wrong surface for anything that must run before the model or must fail a turn. See Hook boundaries.

defineHook is unrelated to Cursor Agent hooks, the .cursor/hooks.json scripts that can observe, block, or modify the agent loop. Those still run inside a local session workspace.

Author a hook

Author bot/hooks/<name>.ts with defineHook from @grok/agent-sdk/hooks. This hook meters tokens and pages on failure:

// bot/hooks/usage.tsimport { metrics } from "@opentelemetry/api";import { defineHook } from "@grok/agent-sdk/hooks";const meter = metrics.getMeter("acme");const inputTokens = meter.createCounter("acme.tokens.input");const turnFailed = meter.createCounter("acme.turn.failed");export default defineHook({  events: {    async "turn.completed"(event, ctx) {      if (ctx.session.purpose === "eval" || event.data.usage === undefined) {        return;      }      inputTokens.add(event.data.usage.inputTokens);    },    async "turn.failed"(event, ctx) {      const pagerUrl = process.env.PAGER_WEBHOOK_URL;      if (        pagerUrl === undefined ||        ctx.session.purpose === "eval" ||        event.data.status === "cancelled"      ) {        return;      }      turnFailed.add(1, { channel: ctx.channel.id });      await fetch(pagerUrl, {        method: "POST",        headers: { "content-type": "application/json" },        body: JSON.stringify({          agent: ctx.agent.name,          session: ctx.session.id,          message: event.data.message,        }),        signal: AbortSignal.timeout(5_000),      });    },  },});

Any module under bot/hooks/ is a hook named by its path without the extension. *.test.ts and *.spec.ts are skipped. The default export must be defineHook(...), names can't contain __, and an empty events map is skipped with a warning. agent-sdk validate reports all three. An extension mounts its hooks as <ns>__<name>, and disableHook() removes one. See Adjust a mounted extension.

agent-sdk init scaffolds bot/hooks/memory.ts. Delete it to opt out of the journal. See Memory.

Read hosted secrets inside the handler, not at module scope. See Add egress and secrets. Give outbound calls a timeout, because a stalled request blocks later handlers on that session.

Events and payloads

Keys are event types from the event vocabulary, or "*" for every event. A typed key narrows event.data, a "*" handler receives the union so you switch on event.type, and every event carries { type, index, sessionId, turnId?, at, data }. Skip *.appended deltas when you want the final text.

The types are SessionEvent, SessionEventType, and HookContext, exported from @grok/agent-sdk.

Handler context

Hook dispatch

A hook runs after the event is recorded. It never delays the model.

Hook boundaries

To act on a turn's decision, such as a label or a ticket, have the model record it with an authored tool. A turn.completed hook then reads the recorded decision and acts on it through ctx.host.

Test a hook

A hook definition is a plain object, so a unit test calls hook.events["turn.completed"] directly with an event and a stub HookContext. Discovery skips *.test.ts, so the test can live next to the hook.

On hosting, read the same log with agent-sdk logs.

See also Sessions, OpenTelemetry, and Channels.