@cursor/july 0.1.113 → 0.2.0

package/docs/reference/hooks.md

@@ -5,18 +5,16 @@ description: "Observe-only subscribers to the session event stream: audit logs,
 
 # Hooks
 
-A hook subscribes to the session event stream and runs a side effect
-after each event is recorded: an audit line, a metric, a copy of the
-transcript in your own store, or derived state for later turns. Hooks
-run in the serving process for every session of the agent, on local and
-cloud runtime turns alike.
-
-Hooks observe. They can't change the turn, the prompt, or the reply, and
-a handler that throws is logged and skipped. Treat the event as
-read-only; later subscribers see the same object. That makes hooks safe
-to add to a production agent, and the wrong tool for anything that must
-happen before the model runs or must fail a turn; see
-[When not to use a hook](#when-not-to-use-a-hook).
+A hook subscribes to selected session events and can run a side effect
+after each matching event is recorded: an audit line, a metric, a
+transcript copy, or derived state. Hooks run for every session of the
+agent, on local and cloud turns alike. 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.
+That makes hooks safe to add to a production agent, and the wrong
+surface for anything that must run before the model or must fail a
+turn; see [Hook boundaries](#hook-boundaries).
 
 `defineHook` is unrelated to
 [Cursor Agent hooks](https://cursor.com/docs/agent/hooks), the
@@ -65,95 +63,54 @@ later sessions to read. Delete the file to opt out.
 ## Events and payloads
 
 Keys are event types from the
-[event vocabulary](./sessions.md#which-events-can-i-stream), or `"*"`
+[event vocabulary](./sessions.md#stream-events), or `"*"`
 for every event. A typed key narrows `event.data`; a `"*"` handler
 receives the union, so switch on `event.type`. Every event carries the
 stream envelope `{ type, index, sessionId, turnId?, at, data }`, with
-`turnId` set on turn-scoped events.
-
-The payloads hooks read most often:
+`turnId` set on turn-scoped events. Skip `*.appended` deltas when you
+want the final text; `message.completed` already has it.
 
 | Event               | `event.data`                                                                                                                                                                                                |
 | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `message.received`  | `{ text }`                                                                                                                                                                                                  |
 | `turn.completed`    | `{ result?, usage?, cost? }`. `usage` has `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`, and optional `reasoningTokens`. `cost` has `totalUsd` and the `model` it was priced against |
-| `turn.failed`       | `{ message }`                                                                                                                                                                                               |
-| `actions.requested` | `{ calls: [{ callId, toolName, args? }] }`. A call with `parentCallId` belongs to a subagent                                                                                                                |
-| `action.result`     | `{ callId, toolName, output?, isError, stubbed? }`. `stubbed` means a dry-run session answered a write without running it                                                                                   |
+| `turn.failed`       | `{ message, status? }`. `status` is `"error"` or `"cancelled"` when present                                                                                                                                 |
+| `actions.requested` | `{ calls: [{ callId, toolName, args?, parentCallId? }], parentCallId? }`. `parentCallId` marks subagent work                                                                                                |
+| `action.result`     | `{ callId, toolName, output?, isError, stubbed?, parentCallId? }`. `stubbed` means a dry-run session answered a write without running it                                                                    |
 
 The types are `SessionEvent`, `SessionEventType`, and `HookContext`,
 exported from `@cursor/july`.
 
 ## Handler context
 
-| Member                                              | What it is                                                                                                                                                                    |
-| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ctx.session`                                       | Read-only session info: `id`, `channelId`, `mode` (`chat` or `task`), `purpose` (`live` or `eval`), `auth`, plus `title` and `sdkAgentId` when set                            |
-| `ctx.agent`                                         | `{ name }` of the agent the event belongs to                                                                                                                                  |
-| `ctx.channel`                                       | `{ id, continuationToken }`. The token is `null` when the session can't take follow-ups                                                                                       |
-| `ctx.host.kv`                                       | Durable JSON, shared by every session of the agent; the storage backend decides whether it survives a hosted replace. Prefix keys with `ctx.session.id` for per-session state |
-| `ctx.host.files`                                    | Durable files, bound to this session. Pass `{ scope: "deployment" }` for agent-wide files                                                                                     |
-| `ctx.host.otel`                                     | Counters, histograms, and tags, attributed to this session                                                                                                                    |
-| `ctx.host.mcp`, `ctx.host.github`, `ctx.host.slack` | The same shared clients tools get                                                                                                                                             |
-| `ctx.host.reminders`                                | Per-session [reminders](./schedules.md), the same API tools get                                                                                                               |
-| `ctx.artifacts`                                     | Session-bound [artifacts](./artifacts.md) facade: `tag` fills in `sessionId` and `turnId`                                                                                     |
-| `ctx.stateRoot`                                     | Absolute path of the local state root. It resets when a hosted deployment is replaced; keep derived state in `kv` or `files`                                                  |
-
-## When hooks run
-
-A hook runs after the event is durably recorded. It never delays the
-model turn and never sees an event that wasn't recorded.
-
-Within one session, events dispatch in order, one at a time: the
-channel's `events` handlers first, then each hook in discovery order.
-Sessions don't wait on each other.
-
-Two consequences:
-
-- A slow handler holds up the next event's handlers for that session,
-  not the model. Keep handlers short and queue anything slow.
-- Hooks fire for eval sessions too. Check
-  `ctx.session.purpose === "eval"` before metering or paging.
-
-Each event reaches a hook at most once. A restart doesn't replay the log
-into hooks, so a mirror needs no dedupe, and the event log rather than
-the hook's copy is the source of truth.
-
-## Hooks, channel events, or evals?
-
-All of them consume the same stream, for different jobs:
-
-|                    | Hooks                                           | Channel `events`                                                  | Evals                             |
-| ------------------ | ----------------------------------------------- | ----------------------------------------------------------------- | --------------------------------- |
-| Scope              | every session of the agent                      | sessions the channel owns                                         | one test turn                     |
-| Job                | observe: audit, metrics, mirrors, derived state | deliver: replies back to the channel's surface                    | assert: gates over the trajectory |
-| Context            | `ctx.host`, `ctx.artifacts`, session info       | `channel.state`, `setContinuationToken`, `ctx.host`, session info | the `t` assertion helpers         |
-| Can affect the run | no                                              | yes, it owns the surface                                          | n/a                               |
-| Authored at        | `agent/hooks/*.ts`                              | channel config                                                    | `evals/**/*.eval.ts`              |
-
-## When not to use a hook
-
-| You want to                                                                           | Use instead                                                                                                      |
-| ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| Add context before the model runs                                                     | The channel's `send` message and `workspaceFiles`, `instructions.md`, skills, or `sandbox/workspace/` seed files |
-| Reply on Slack, comment on a PR, or post any other delivery                           | The channel's `events` map, or the Slack and GitHub packs                                                        |
-| Show PR progress (merge-box check, sticky banner)                                     | `githubChannel({ progress: { commitStatus, banner } })`; see the [PR autofixer](../templates/pr-autofixer.md)    |
-| Block, approve, or rewrite a tool call                                                | [`needsApproval`](./tools.md#gate-a-tool-on-human-approval) on the tool                                          |
-| Act on the final assistant text, reject it for a same-turn repair, or fail a bad turn | `defineResult`                                                                                                   |
-| Gate a change on behavior                                                             | [Evals](../evals.md)                                                                                             |
-
-## Patterns
-
-Usage metering is the [authoring example](#author-a-hook). Three more:
-
-### Alert on failure
-
-`turn.failed` carries the message, and `ctx.session.id` points at the
-trace. Skip interrupted turns; those are preemptions, not failures. Read
-secrets inside the handler: hosted deployments bind them after the
-process starts, so a module-scope read stays empty. Give the call a
-timeout, since a stalled request holds up later handlers on that
-session.
+| Member                                              | What it is                                                                                                                                                 |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ctx.session`                                       | Read-only session info: `id`, `channelId`, `mode` (`chat` or `task`), `purpose` (`live` or `eval`), `auth`, plus `title` and `sdkAgentId` when set         |
+| `ctx.agent`                                         | `{ name }` of the agent the event belongs to                                                                                                               |
+| `ctx.channel`                                       | `{ id, continuationToken }`. The token is `null` when the session can't take follow-ups                                                                    |
+| `ctx.host.kv`                                       | Durable JSON, shared by every session of the agent. Prefix keys with `ctx.session.id` for per-session state                                                |
+| `ctx.host.files`                                    | Durable files, bound to this session. Pass `{ scope: "deployment" }` for agent-wide files                                                                  |
+| `ctx.host.otel`                                     | Counters, histograms, and tags, attributed to this session                                                                                                 |
+| `ctx.host.mcp`, `ctx.host.github`, `ctx.host.slack` | The same shared clients tools get                                                                                                                          |
+| `ctx.host.reminders`                                | Per-session [reminders](./schedules.md#reminders), the same API tools get                                                                                  |
+| `ctx.artifacts`                                     | Session-bound [artifacts](./artifacts.md) facade: `tag` fills in `sessionId` and `turnId`                                                                  |
+| `ctx.stateRoot`                                     | Absolute path of the local state root. It resets when a hosted deployment is replaced; keep derived state in `kv` or `files`                               |
+
+## Hook dispatch
+
+A hook runs after the event is recorded. It never delays the model and
+never sees an event that wasn't recorded.
+
+| Rule | What happens |
+| --- | --- |
+| Same session | Events dispatch one at a time |
+| Eval sessions | The same stream fires; skip metering or paging when `ctx.session.purpose === "eval"` |
+| Host restart | Recorded events are not replayed into hooks, so a mirror needs no dedupe |
+| Slow handler | Holds the next event's handlers on that session, not the model. Keep handlers short and queue anything slow |
+
+Read hosted secrets inside the handler, not at module scope. Give
+outbound calls a timeout; a stalled request holds later handlers on that
+session. Skip cancelled turns when paging; they record interrupted work.
 
 ```ts
 // agent/hooks/page-on-failure.ts
@@ -166,7 +123,7 @@ export default defineHook({
       if (
         pagerUrl === undefined ||
         ctx.session.purpose === "eval" ||
-        event.data.message === "turn interrupted"
+        event.data.status === "cancelled"
       ) {
         return;
       }
@@ -186,78 +143,47 @@ export default defineHook({
 });
 ```
 
-### Mirror the transcript
+## Hooks vs channels vs evals
 
-Subscribe to `"*"` and write one file per event, skipping the
-`*.appended` deltas: they arrive per token, and `message.completed`
-carries the final text. Session scope keeps transcripts apart without a
-session id in the path. The mirror holds reasoning text and raw tool
-arguments and outputs, so pick the store accordingly, and write to your
-own store instead when you need cross-session queries.
+All three consume the same stream, for different jobs:
 
-```ts
-// agent/hooks/mirror.ts
-import { defineHook } from "@cursor/july/hooks";
-
-export default defineHook({
-  events: {
-    async "*"(event, ctx) {
-      if (event.type.endsWith(".appended")) {
-        return;
-      }
-      const name = String(event.index).padStart(6, "0");
-      await ctx.host.files.write(
-        `transcript/${name}.json`,
-        JSON.stringify(event)
-      );
-    },
-  },
-});
-```
-
-### Keep derived state across a replace
-
-Write it to `ctx.host.kv` under a session-prefixed key; a tool reads it
-back with `ctx.host.kv.get`.
+|                    | Hooks                                           | Channel `events`                                                  | Evals                             |
+| ------------------ | ----------------------------------------------- | ----------------------------------------------------------------- | --------------------------------- |
+| Scope              | every session of the agent                      | sessions the channel owns                                         | one test turn                     |
+| Job                | observe: audit, metrics, mirrors, derived state | deliver: replies back to the channel's surface                    | assert: gates over the trajectory |
+| Context            | `ctx.host`, `ctx.artifacts`, session info       | `channel.state`, `setContinuationToken`, `ctx.host`, session info | the `t` assertion helpers         |
+| Can affect the run | no                                              | yes, it owns the surface                                          | n/a                               |
+| Authored at        | `agent/hooks/*.ts`                              | channel config                                                    | `evals/**/*.eval.ts`              |
 
-```ts
-// agent/hooks/last-result.ts
-import { defineHook } from "@cursor/july/hooks";
+## Hook boundaries
 
-export default defineHook({
-  events: {
-    async "turn.completed"(event, ctx) {
-      await ctx.host.kv.put(`last-result/${ctx.session.id}`, {
-        at: event.at,
-        result: event.data.result ?? null,
-      });
-    },
-  },
-});
-```
+| You want to                                                                           | Use instead                                                                                                      |
+| ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| Add context before the model runs                                                     | The channel's `send` message and `workspaceFiles`, `instructions.md`, skills, or `sandbox/workspace/` seed files |
+| Reply on Slack, comment on a PR, or post any other delivery                           | The channel's `events` map, or the Slack and GitHub packs                                                        |
+| Show PR progress (merge-box check, sticky banner)                                     | `githubChannel({ progress: { commitStatus, banner } })`; see the [PR autofixer](../templates/pr-autofixer.md)    |
+| Block, approve, or rewrite a tool call                                                | [`needsApproval`](./tools.md#gate-a-tool-on-human-approval) on the tool                                          |
+| Act on the final assistant text, reject it for a same-turn repair, or fail a bad turn | `defineResult`                                                                                                   |
+| Gate a change on behavior                                                             | [Evals](../evals.md)                                                                                             |
 
-## Test and debug a hook
+## 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.
 
-At runtime:
-
-- `agent-sdk validate --dir .` reports discovery errors and the
-  empty-handlers warning.
-- `agent-sdk info --dir . --json` lists the loaded hooks under
-  `agents[].hooks`.
-- Send a turn with `agent-sdk dev` or `agent-sdk run --dir . --message "…"`
-  and watch the serve log for
-  `hook "<name>" handler for <event> threw: …`. `run` prints that log on
-  stderr. On hosting, read it with [`agent-sdk logs`](./cli.md#logs).
+| Command | What it reports |
+| --- | --- |
+| `agent-sdk validate --dir .` | Discovery errors and the empty-handlers warning |
+| `agent-sdk info --dir . --json` | Loaded hooks under `agents[].hooks` |
+| `agent-sdk run --dir . --message "…"` | Serve log on stderr, including `hook "<name>" handler for <event> threw: …` |
 
-## What's next
+On hosting, read the same log with [`agent-sdk logs`](./cli.md#logs).
 
-Continue with these pages:
+## Related
 
+- [Hooks guide](../guides/hooks.md): meter usage and page on failure
 - [Sessions and streaming](./sessions.md): the event vocabulary hooks observe
 - [OpenTelemetry](../guides/opentelemetry.md): OTLP traces and metrics
   from the same event stream