@cursor/july 0.1.112 → 0.1.114

package/dist/docs/llms-full.txt

@@ -331,7 +331,7 @@ per-caller and channel-specific auth.
 
 Use `agent-sdk logs --prod` for runtime output,
 [OpenTelemetry](/docs/guides/opentelemetry.md) for traces and metrics, and
-[session traces](/docs/reference/sessions.md#how-do-i-inspect-a-saved-event-stream)
+[session traces](/docs/reference/sessions.md#inspect-a-saved-event-stream)
 for one conversation.
 
 ## Related
@@ -366,6 +366,9 @@ This smoke case asks for a PR verdict, requires the read-only inspection
 tool, and fails if the agent tries to approve. The CLI reports all three
 decisions together instead of stopping at the first miss.
 
+Use the [Jev extension](/docs/guides/jev.md) when host code needs a typed
+choice, score, or boolean before it writes.
+
 ```ts
 // evals/readiness.eval.ts
 import { defineEval, includes } from "@cursor/july/evals";
@@ -606,32 +609,21 @@ moves the freeze line instead of proving the change.
 
 Source: /docs/guides/agent-to-agent.md
 
-# Agent-to-agent
+# Peer agents
 
 A peer connection lets one agent ask another agent on the same host for
 help. The specialist keeps its own instructions, tools, and session,
 while the caller decides when to delegate and returns the answer to the
-user.
-
-## How do I wire two agents?
+user. Co-host both projects under one `agent-sdk` process.
 
-Put both projects under one directory, then point the concierge at the
-specialist's mount slug. When a user asks about weather, the concierge
-calls the peer's `ask` tool, the weather agent runs in its own context,
-and the concierge returns that answer.
+## Delegate a question to a specialist
 
-```text
-agents/
-  concierge/
-    agent/instructions.md
-    agent/mcp-connections/weather.ts
-  weather-agent/
-    agent/agent.ts
-    agent/instructions.md
-```
+Ask the concierge about the weather and it hands the question to the
+specialist. The weather agent answers in its own context, then the
+concierge returns that answer to you.
 
 ```ts
-// agents/concierge/agent/mcp-connections/weather.ts
+// agent/mcp-connections/weather.ts
 import { defineConnection } from "@cursor/july/connections";
 
 export default defineConnection({
@@ -644,7 +636,7 @@ Give the concierge a narrow routing rule:
 
 ```md
 When a request needs current weather, ask the `weather` peer. Return its
-answer without delegating the same request again.
+answer.
 ```
 
 ```bash
@@ -653,58 +645,69 @@ agent-sdk chat --url http://127.0.0.1:3000/concierge \
   --message "What's the weather in Paris right now?"
 ```
 
-The connection filename becomes the MCP server name. The `agent` value
-is the specialist's mount slug, normally its directory name.
+The connection filename is the MCP server name the concierge calls, and
+`agent` is the specialist's mount slug, normally its directory name.
 
-## Continue the specialist's conversation
+## Continue the specialist's session
 
-The first `ask` returns a peer `sessionId`. Pass that ID into the next
-`ask` when the specialist should remember its earlier work instead of
-starting with fresh context.
+Ask a follow-up about the same forecast and the specialist picks up
+where it left off, with its own instructions and tool history still in
+place. The first `ask` returns `{ status, sessionId, reply }` as text on
+the `callTool` result. Parse `sessionId` and pass it on the next `ask`
+so the peer remembers its earlier work instead of starting fresh.
 
-```json
-{
-  "message": "How does that compare with tomorrow?",
-  "sessionId": "<session-id>"
+```ts
+const first = await ctx.host.mcp.callTool("weather", "ask", {
+  message: "What's the weather in Paris right now?",
+});
+const firstText = first.content.find((part) => part.type === "text");
+if (firstText?.text === undefined) {
+  throw new Error("weather ask returned no text payload");
 }
-```
-
-The peer owns this session. Follow-ups resume its instructions and tool
-history without merging them into the concierge's conversation.
+const { sessionId } = JSON.parse(firstText.text) as { sessionId: string };
 
-## Wait for long-running specialist work
+await ctx.host.mcp.callTool("weather", "ask", {
+  message: "How does that compare with tomorrow?",
+  sessionId,
+});
+```
 
-`ask` waits for a bounded time. If the specialist is still working, it
-returns `status: "running"` with the session ID, allowing the caller to
-do other work and check again later.
+If the specialist is still working, `ask` returns `status: "running"`
+with the session ID, and you can do other work before calling `check`.
 
-```json
-{
-  "sessionId": "<session-id>",
-  "waitSeconds": 20
-}
+```ts
+await ctx.host.mcp.callTool("weather", "check", {
+  sessionId,
+  waitSeconds: 20,
+});
 ```
 
-Call the peer's `check` tool with that input. It returns the final reply
-when the turn settles, or another running status when more time is
-needed.
+The peer owns this session, so follow-ups continue the specialist's
+context.
 
 ## Call a deterministic peer tool
 
-When the specialist has a server tool and no second model turn should
-make a decision, call its `call_tool` endpoint through the peer
-connection. This example runs `get_forecast` in the weather agent's
-workspace and returns its structured result to the concierge tool.
+You need a forecast for Paris, and the weather agent already has
+`get_forecast`. Host code calls that tool in the specialist's workspace
+and the forecast comes back to the concierge, with no second model turn.
 
 ```ts
 const result = await ctx.host.mcp.callTool("weather", "call_tool", {
   toolName: "get_forecast",
   input: { city: "Paris" },
 });
+const part = result.content.find((item) => item.type === "text");
+if (part?.text === undefined) {
+  return { ok: false, forecast: null };
+}
+const payload = JSON.parse(part.text) as {
+  isError?: boolean;
+  result?: unknown;
+};
 
 return {
-  ok: result.isError !== true,
-  forecast: result.structuredContent ?? null,
+  ok: result.isError !== true && payload.isError !== true,
+  forecast: payload.result ?? null,
 };
 ```
 
@@ -723,27 +726,31 @@ complete agent you would also run, inspect, or expose on its own.
 | Tools and connections | Inherits the parent project | Owns its project surface |
 | Reachability | Parent only | Other co-hosted agents and MCP clients |
 
-## Peer sessions
+## Affinity
 
-Calls through `ask` create sessions on the peer's `mcp` channel. They
-use the caller's authenticated principal and appear in the peer's
-playground, so the same authorization boundary applies to starts,
-follow-ups, and checks.
+Those turns show up in the peer's playground. Only the session owner
+can continue or check them.
 
-There is no automatic recursion guard between peers. Give each caller a
-one-way routing rule so agent A cannot delegate the same work to B and
-receive it back from B.
+## Practices
 
-## Run peers on one host
+- Give each caller a one-way routing rule, and don't configure reciprocal
+  routes for the same request.
 
-Peers require the default multi-agent layout and one shared `serve`
-process. Unknown slugs and self-references fail at startup.
-Cursor-managed hosting deploys one agent per slug, so use subagents
-there instead of peer connections.
+- Prefer `ask` when the specialist should reason. Use `call_tool` when
+  host code already knows which server tool to run.
 
-For a self-hosted cloud-runtime caller, expose the shared process with
-`--public-url` and protect it with `--bearer-token`. The
-[Deployment guide](/docs/deployment.md) owns that hosting setup.
+- Cursor-managed hosting deploys one agent per slug. Use
+  [subagents](/docs/reference/subagents.md) there instead of peer
+  connections.
+
+## Other hosts
+
+Peers require the default multi-agent layout; unknown slugs and
+self-references fail at startup.
+
+If a cloud-runtime turn needs a self-hosted peer, set `--public-url` to
+the shared host's reachable URL and protect it with `--bearer-token`.
+The [Deployment guide](/docs/deployment.md) owns that hosting setup.
 
 ## Related
 
@@ -1056,7 +1063,7 @@ agent, keep talking while it works, inspect the result, and steer or
 stop the same branch.
 
 This is different from choosing
-[`runtime: "cloud"`](/docs/reference/agent-config.md#choose-a-runtime).
+[`runtime: "cloud"`](/docs/reference/agent-config.md#runtime).
 That setting moves this agent's turns to a cloud VM; this extension lets
 the agent delegate separate coding tasks.
 
@@ -2153,11 +2160,127 @@ directory and disable that tool. See
   overlays
 - [Tool approvals](/docs/reference/tools.md#gate-a-tool-on-human-approval):
   approve asks
-- [Agent config](/docs/reference/agent-config.md#choose-a-runtime): local
+- [Agent config](/docs/reference/agent-config.md#runtime): local
   and hosted runtimes
 
 ---
 
+Source: /docs/guides/hooks.md
+
+# Hooks
+
+Hooks observe session events after they are recorded and run side effects such
+as updating metrics or sending alerts. They never change the turn, prompt, or
+reply. Author them under `agent/hooks/` with `defineHook` from
+`@cursor/july/hooks`.
+
+## Meter token usage
+
+With [OpenTelemetry](/docs/guides/opentelemetry.md) configured, this hook adds a live
+turn's reported input and output tokens to your counters. Eval runs stay quiet,
+so the dashboard reflects live traffic instead of the test suite.
+
+```ts
+// agent/hooks/usage.ts
+import { defineHook } from "@cursor/july/hooks";
+
+export default defineHook({
+  events: {
+    async "turn.completed"(event, ctx) {
+      if (ctx.session.purpose === "eval") {
+        return;
+      }
+      if (event.data.usage === undefined) {
+        return;
+      }
+
+      const { inputTokens, outputTokens } = event.data.usage;
+      ctx.host.otel.increment("acme.tokens.input", inputTokens);
+      ctx.host.otel.increment("acme.tokens.output", outputTokens);
+    },
+  },
+});
+```
+
+## Alert on failure
+
+Set `PAGER_WEBHOOK_URL` to your pager's webhook. When a live turn fails, this
+hook posts the agent, session, and failure message there. Eval runs and
+interrupted turns stay quiet, so tests and preemptions do not page anyone.
+
+```ts
+// agent/hooks/page-on-failure.ts
+import { defineHook } from "@cursor/july/hooks";
+
+export default defineHook({
+  events: {
+    async "turn.failed"(event, ctx) {
+      if (ctx.session.purpose === "eval") {
+        return;
+      }
+      if (event.data.message === "turn interrupted") {
+        return;
+      }
+
+      const pagerUrl = process.env.PAGER_WEBHOOK_URL;
+      if (pagerUrl === undefined) {
+        return;
+      }
+
+      await fetch(pagerUrl, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          agent: ctx.agent.name,
+          session: ctx.session.id,
+          channel: ctx.channel.id,
+          message: event.data.message,
+        }),
+        signal: AbortSignal.timeout(5_000),
+      });
+    },
+  },
+});
+```
+
+## Events / when hooks run
+
+Use event names from the
+[session event vocabulary](/docs/reference/sessions.md#stream-events). A hook
+receives each matching event after it is recorded, and the model does not wait
+for the handler.
+
+Within one session, handlers run one at a time. A slow handler delays later
+handlers for that session, but it does not delay the model or handlers for
+other sessions. Hooks also fire for evals, so check
+`ctx.session.purpose === "eval"` before metering or paging. A restart does not
+replay recorded events into hooks.
+
+## When not to use a hook
+
+| Want | Use instead |
+| --- | --- |
+| Add context before the model | `instructions.md`, skills, or `workspaceFiles` |
+| Deliver to Slack or a PR | Channel [`events`](/docs/reference/channels.md#events) or packs |
+| Block or approve a tool | [`needsApproval`](/docs/reference/tools.md#gate-a-tool-on-human-approval) |
+| Gate final assistant text | `defineResult` |
+| Gate behavior | [Evals](/docs/evals.md) |
+
+[Cursor Agent hooks](https://cursor.com/docs/agent/hooks) in
+`.cursor/hooks.json` are a different product. They can observe, block, or
+modify the local agent loop.
+
+## Related
+
+- [Hooks reference](/docs/reference/hooks.md): payloads, context, and discovery
+- [Sessions: stream events](/docs/reference/sessions.md#stream-events): event
+  vocabulary and payload sequence
+- [OpenTelemetry](/docs/guides/opentelemetry.md): export traces and custom metrics
+- [Channels: events](/docs/reference/channels.md#events): deliver replies back to
+  Slack, source control, or another surface
+
+---
+
 Source: /docs/guides/improve.md
 
 # Self-improvement
@@ -2307,6 +2430,302 @@ replace them.
 
 ---
 
+Source: /docs/guides/jev.md
+
+# Use Jev in review tools
+
+Use Jev when a review workflow needs a typed decision instead of prose.
+A review agent can filter speculative findings, classify pull request
+risk, choose a reviewer, or decide whether a merge needs a documentation
+follow-up. Jev returns a choice, score, or probability; your TypeScript
+decides what happens next.
+
+Set `TYPESAFE_API_KEY`. The default model is `jev-latest`.
+
+```ts
+// agent/extensions/jev.ts
+import jev from "@cursor/july/extensions/jev";
+
+export default jev();
+```
+
+## Start only the review turns you need
+
+Call Jev from a channel hook before a model turn starts. When a pull
+request opens or becomes ready for review, this hook sends its title,
+body, labels, and filenames to Jev to decide whether the change needs
+security review. A result that clears the threshold starts the review
+turn; otherwise, the hook returns `null`, so the agent doesn't run or
+post to GitHub.
+
+```ts
+// agent/channels/github.ts
+import {
+  defaultGitHubAuth,
+  githubChannel,
+} from "@cursor/july/channels/github";
+import { above, decide } from "@cursor/july/extensions/jev";
+
+export default githubChannel({
+  botName: "security-reviewer",
+  cursorAccount: { repos: ["acme/checkout"] },
+  onPullRequest: async (ctx, pr) => {
+    if (pr.action !== "opened" && pr.action !== "ready_for_review") {
+      return null;
+    }
+
+    const octokit = await ctx.github.getOctokit();
+    const [{ data }, files] = await Promise.all([
+      octokit.rest.pulls.get({
+        owner: ctx.repository.owner,
+        repo: ctx.repository.name,
+        pull_number: pr.number,
+      }),
+      octokit.paginate(octokit.rest.pulls.listFiles, {
+        owner: ctx.repository.owner,
+        repo: ctx.repository.name,
+        pull_number: pr.number,
+      }),
+    ]);
+    const answers = await decide({
+      state: {
+        title: data.title,
+        body: data.body,
+        labels: data.labels.map(label => label.name),
+        files: files.map(file => file.filename),
+      },
+      questions: {
+        review: {
+          type: "boolean",
+          instructions:
+            "Does this change need security review? Answer yes for auth, permissions, secrets, request parsing, or external inputs.",
+        },
+      },
+    });
+
+    if (!above(answers.review, 0.8)) {
+      return null;
+    }
+    // `auth` starts a model turn running as the pull request sender.
+    return { auth: defaultGitHubAuth(ctx) };
+  },
+});
+```
+
+Jev receives only the pull request metadata shown here, not the diff.
+
+## Filter findings before you post them
+
+Let the chat model draft a finding, then ask Jev whether the finding is
+a real bug in the new code. Below your threshold, the tool returns and
+the author never sees the draft. Above it, the finding becomes a review
+comment.
+
+```ts
+// agent/tools/post_finding.ts
+import { parseGitHubPrContinuationKey } from "@cursor/july/channels/github";
+import { above, decide } from "@cursor/july/extensions/jev";
+import { defineTool } from "@cursor/july/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description:
+    "Post one security finding on this session's pull request. Call once. Hold when it is not a real bug.",
+  inputSchema: z.object({
+    title: z.string(),
+    summary: z.string().describe("What the pull request changes."),
+    draft: z.string().describe("The finding to post, one or two sentences."),
+  }),
+  async execute({ title, summary, draft }, ctx) {
+    if (ctx.session.purpose === "eval") {
+      return { posted: false, reason: "eval" };
+    }
+
+    const ref = parseGitHubPrContinuationKey(ctx.session.continuationKey ?? "");
+    if (ref === undefined) {
+      throw new Error("post_finding requires a GitHub pull request session");
+    }
+
+    const answers = await decide({
+      state: { title, summary, draft },
+      questions: {
+        real: {
+          type: "boolean",
+          instructions:
+            "Is the draft an exploitable bug in the new code, not a style note or a hypothetical?",
+        },
+      },
+    });
+
+    if (!above(answers.real, 0.85)) {
+      return { posted: false, reason: "clean" };
+    }
+
+    const octokit = await ctx.host.github.getOctokit();
+    await octokit.rest.pulls.createReview({
+      owner: ref.owner,
+      repo: ref.repo,
+      pull_number: ref.number,
+      event: "COMMENT",
+      body: draft,
+    });
+    return {
+      posted: true,
+      pr: `${ref.owner}/${ref.repo}#${ref.number}`,
+    };
+  },
+});
+```
+
+## Approve changes by risk tier
+
+You can use the same pattern for Agentic Owners. Ask Jev to put the
+pull request in a closed set of risk tiers. Approve only a confident
+`very-low` or `low`; send everything else to a person.
+
+```ts
+import { decide, needsHuman } from "@cursor/july/extensions/jev";
+
+const answers = await decide({
+  state: { title, summary },
+  questions: {
+    risk: {
+      type: "choice",
+      instructions: "What risk tier is this pull request?",
+      criteria: {
+        "very-low": "docs, formatting, or a mechanical rename",
+        low: "a local change with tests and no new trust boundary",
+        medium: "auth, billing, or a behavior change callers depend on",
+        high: "a likely exploit, data loss, or a broken public contract",
+      },
+    },
+  },
+});
+
+const tier = answers.risk.choice;
+if (needsHuman(answers.risk) || tier === "medium" || tier === "high") {
+  return { verdict: "hold", tier };
+}
+return { verdict: "approve", tier };
+```
+
+Your GitHub tool resolves the pull request from `ctx.session` and posts
+that verdict. The model does not choose the repository, pull request, or
+approval event.
+
+## Open documentation follow-ups selectively
+
+After a pull request merges, a code-wiki agent can ask whether the
+change introduced a durable fact that belongs in the docs. A low
+probability skips the follow-up, while a high probability opens a
+documentation pull request.
+
+```ts
+import { above, decide } from "@cursor/july/extensions/jev";
+import { openDocsPullRequest } from "../lib/wiki";
+
+const answers = await decide({
+  state: { title, summary },
+  questions: {
+    updateDocs: {
+      type: "boolean",
+      instructions:
+        "Does this merge change a durable contract that the project docs should explain?",
+    },
+  },
+});
+
+if (!above(answers.updateDocs, 0.8)) {
+  return { action: "skip" };
+}
+return openDocsPullRequest({ title, summary });
+```
+
+## Write tools with Jev
+
+Call `decide` from a channel hook, server tool, or router when you want
+the answer map directly. Use `evaluate` when you want `{ answers }`.
+
+Use a boolean for a yes-or-no gate, a choice for a closed set such as
+risk tiers or owners, and a score for an ordered rubric. `above` returns
+`true` when a boolean probability or score meets the threshold.
+`needsHuman` returns `true` when a boolean probability or the selected
+choice's probability falls below the confidence threshold.
+
+Keep the questions atomic and combine them in TypeScript. For example,
+ask separately whether a finding is real, whether its impact is
+user-visible, and whether the changed line is new. Your code owns the
+rule that decides whether all three are enough to post.
+
+## Let the agent ask Jev
+
+Mounting the extension adds a read-only harness tool named
+`<namespace>__evaluate`. With the `agent/extensions/jev.ts` mount shown
+earlier, the model sees `jev__evaluate`.
+
+The tool accepts one state and a list of boolean, choice, or score
+questions. It returns `{ answers }` and never posts, approves, or opens
+a pull request. Use it when the agent needs the result during the turn.
+Use `decide` inside a project tool when the answer and the write belong
+in one operation.
+
+## Skills included with the extension
+
+The extension adds two skills by default:
+
+- `jev__questions` teaches the model how to structure atomic questions,
+  choose a question type, and read the answers.
+
+- `jev__gated-write` teaches the model to put `decide` and the write in
+  one server tool, hold on low confidence, and skip writes during evals.
+
+The model sees each skill's description and loads the full procedure
+when it applies.
+
+## Choose what to mount
+
+Both contribution groups are on by default. Turn off the harness tool
+when Jev should only run inside tools you wrote. Turn off the skills
+when your agent already has its own Jev instructions.
+
+```ts
+// agent/extensions/jev.ts
+import jev from "@cursor/july/extensions/jev";
+
+export default jev({
+  harnessTools: false,
+  skills: true,
+});
+```
+
+`harnessTools: false` removes `jev__evaluate` from discovery.
+`skills: false` removes both Jev skills. These switches do not remove
+the exported helpers, so project tools can still import `decide`,
+`above`, and `needsHuman`.
+
+## Practices
+
+- Pass the pull request title, a short summary, and the draft finding.
+  Don't send the checkout.
+
+- Calibrate `above` and `needsHuman` on pull requests you have already
+  labeled. `needsHuman` defaults to `0.7`.
+
+## Related
+
+- [Agentic owners](/docs/templates/agentic-owners.md): a risk tier, then
+  the host approves or asks for reviewers
+- [Security reviewer](/docs/templates/security-reviewer.md): a finding, or
+  no comment
+- [Thermo review](/docs/templates/thermo-review.md): bugs and breakage,
+  posted the same way
+- [Code wiki](/docs/reference/cli.md#init): documentation
+  follow-ups after a merge
+- [Evals](/docs/evals.md): checks on the full turn
+- [GitHub agents](/docs/guides/github.md): how the review gets onto the pull request
+
+---
+
 Source: /docs/guides/mcp-oauth.md
 
 # Connect a private MCP server with OAuth
@@ -3671,11 +4090,11 @@ coding agent extend the project for you
 
 Source: /docs/reference/agent-config.md
 
-# Agent config (`agent/agent.ts`)
+# Agent config
 
-`agent/agent.ts` default-exports `defineAgent(config)`: which model runs
-the agent, where turns execute, and runtime-specific defaults.
-Everything is optional on the root agent.
+`agent/agent.ts` default-exports `defineAgent(config)`, which sets the
+model, execution runtime, and runtime-specific defaults. Every root
+config field is optional.
 
 ```ts
 import { defineAgent } from "@cursor/july";
@@ -3695,9 +4114,7 @@ export default defineAgent({
 });
 ```
 
-## Fields on `defineAgent`
-
-`defineAgent` accepts these fields.
+## Agent fields
 
 | Field | Type | Meaning |
 | --- | --- | --- |
@@ -3706,14 +4123,14 @@ export default defineAgent({
 | `description` | string | What the agent is for. Required on subagents; the parent model reads it to decide when to delegate. Documentation-only on the root. |
 | `instructions` | string | Inline instructions. Prefer `instructions.md`; this exists for subagents and generated configs. |
 | `runtime` | `"local"` or `"cloud"` | Where turns execute. Default `"local"`. |
-| `cloud` | object | Cloud agent defaults: repos, env, envVars, forwarded to the Cursor SDK. Used when `runtime` is `"cloud"`, and as the base merged under per-session `cloud` send options. |
+| `cloud` | object | Cloud agent defaults: repos, env, envVars. Used when `runtime` is `"cloud"`, and as the base merged under per-session `cloud` send options. |
 | `local` | `{ cwd?, workspaceDir?, sandbox? }` | Local harness defaults; ignored for cloud turns. See [Local options](#local-options). |
-| `hosting` | `{ egressDomains?, secretNames? }` | Managed-hosting declarations read by `agent-sdk deploy`: the pod's egress allowlist and the secret names the agent expects. Ignored by local serving. |
-| `concurrency` | `{ maxRunningTurns? }` | Engine-wide turn admission limit. See [Concurrency](#concurrency). |
+| `hosting` | `{ egressDomains?, secretNames? }` | `agent-sdk deploy` declarations for allowed egress domains and expected secret names. Ignored by local serving. |
+| `concurrency` | `{ maxRunningTurns? }` | Agent-wide turn admission limit. See [Concurrency](#concurrency). |
 | `builtinTools` | `{ reminders? }` | Framework-provided model-facing tools, opted in per capability. See [Built-in tools](#built-in-tools). |
-| `tools` | `ToolName[]` | Allowlist of built-in harness tools offered to the model. Unset = the model's full standard toolset. See [Allowlist built-in harness tools](#allowlist-built-in-harness-tools). |
+| `tools` | `ToolName[]` | Allowlist of built-in harness tools offered to the model. Unset = the model's full standard toolset. See [Harness tools](#harness-tools). |
 
-## Choose a model
+## Model
 
 `model` is a Cursor model id string, or `{ id, params }`. Effort and
 speed are params, not id suffixes. The SDK rejects suffix-style ids
@@ -3735,24 +4152,17 @@ A plain string works when you don't need params:
 model: "composer-2.5",
 ```
 
-## Choose a runtime
+## Runtime
 
-`runtime: "local"` (the default) runs turns on the Cursor SDK harness on
-this machine. Server tools, skills, sandbox seeds, and tool approvals
-all apply.
+`runtime: "local"` (the default) runs turns on this machine. Server
+tools, skills, sandbox seeds, and tool approvals all apply.
 
-`runtime: "cloud"` runs turns on Cursor cloud agents (`bc-…` ids). Pass
-a `cloud` block with the repos the VM carries. Server tools stay
-reachable over authenticated HTTP MCP back to the serve host when
-`--public-url` or `--cloud-tools-url` is set (omitted with a warning
-otherwise), and instructions and agent-tool catalogs are prepended to
-the first prompt, because the local session workspace is not the cloud
-VM.
+`runtime: "cloud"` runs turns on Cursor cloud agents. Pass a `cloud`
+block with the repositories the VM needs. See [Tools](/docs/reference/tools.md) for
+server- and agent-tool behavior on cloud turns.
 
-`validate` warns when `runtime: "cloud"` is combined with agent tools
-(they are described on the first prompt instead of written to the VM),
-when skills or sandbox seeds are present (they sync onto an Agent Store
-rather than the session workspace), and when the `cloud` block is
+`validate` warns when `runtime: "cloud"` is combined with agent tools,
+when skills or sandbox seeds are present, and when the `cloud` block is
 missing.
 
 ## Local options
@@ -3761,18 +4171,15 @@ missing.
 
 `local.workspaceDir` points every session at one shared harness cwd,
 for agents that work inside an existing checkout. It takes precedence
-over `cwd`, and a per-send `workspaceDir` still wins over both. The SDK
-keys its local executor (rules, skills, MCP, ignore mappings) on the
-harness cwd, so a shared directory resolves the workspace once per
-serve process instead of once per session. The trade: sessions share a
-working tree, so a file one turn writes is visible to the next.
+over `cwd`, and a per-send `workspaceDir` still wins over both.
+Sessions share a working tree, so a file one turn writes is visible to
+the next.
 
 `local.sandbox` runs the harness inside Cursor's local sandbox. It's
-off by default, matching the SDK: shell then auto-approves and inherits
-the serve process environment, including any credentials the host
-holds. Turn it on for agents whose turns read untrusted input (webhook
-payloads, PR diffs, inbound chat); it's a real tool boundary rather
-than a prompt-level one.
+off by default: shell then auto-approves and inherits the serve process
+environment, including any credentials the host holds. Turn it on for
+agents whose turns read untrusted input (webhook payloads, PR diffs,
+inbound chat); it's a tool boundary, not a prompt-level one.
 
 ### Local cwd
 
@@ -3788,13 +4195,12 @@ does not leak rules, skills, or MCP servers into the turn. A standalone git
 root keeps the in-project session workspace. Point `cwd` at a checkout only
 when the agent should inherit that tree.
 
-## Allowlist built-in harness tools
+## Harness tools
 
 Use `tools` to limit which built-in Cursor harness tools the model can
 call. Omit it to keep the standard toolset. When you set it, the model
 gets only the tools you list. An empty list disables all native
-built-in tools. Because this field is an allowlist, new platform tools
-stay disabled until you add them.
+built-in tools. New platform tools stay disabled until you add them.
 
 ```ts
 export default defineAgent({
@@ -3805,12 +4211,13 @@ export default defineAgent({
 });
 ```
 
-The Agent SDK always adds `"mcp"` to a configured allowlist. Authored
-server tools in `agent/tools/` use MCP to reach the model. MCP can also
-expose declared connections and servers from the harness directory's
-ambient `.cursor` config. To exclude a checkout's MCP servers, point
-`local.cwd` outside the checkout. See [Local cwd](#local-cwd).
-`local.sandbox` makes MCP tool calls fail closed.
+The Agent SDK always adds `"mcp"` to a configured allowlist, because
+authored server tools in `agent/tools/` reach the model over MCP. MCP
+can also expose declared connections and servers from the harness
+directory's ambient `.cursor` config. To exclude a checkout's MCP
+servers, point `local.cwd` outside the checkout. See
+[Local cwd](#local-cwd). `local.sandbox` makes MCP tool calls fail
+closed.
 
 Use the SDK's public tool names, including `"shell"`, `"read"`,
 `"edit"`, `"grep"`, `"glob"`, `"ls"`, and `"task"`. Unknown names
@@ -3827,8 +4234,7 @@ Two names have broader effects:
 Tool allowlists work only with the local runtime. A
 `runtime: "cloud"` agent that sets `tools` fails at serve startup.
 The Agent SDK also refuses per-send cloud sessions from a hybrid agent
-with an allowlist. It won't run those sessions with unrestricted tool
-access.
+with an allowlist.
 
 The allowlist controls which tools the model can call. It does not
 isolate the serve host. For agents that process untrusted input, also
@@ -3836,10 +4242,10 @@ set `local: { sandbox: true }`.
 
 ## Cloud options
 
-Cloud agent defaults forwarded to the Cursor SDK: `repos` (each
-`{ url, startingRef? }`), environment selection, `envVars`, and the
-rest. A local agent uses the same block as the base config when a
-channel opens a cloud-attached session per send (the `cloud` option on
+The `cloud` block sets default repositories (each
+`{ url, startingRef? }`), environment selection, and `envVars`. A local
+agent uses the same block as the base config when a channel opens a
+cloud-attached session per send (the `cloud` option on
 [`send`](/docs/reference/channels.md#handler-arguments)).
 
 ## Concurrency
@@ -3862,9 +4268,8 @@ export default defineAgent({
 ## Built-in tools
 
 `builtinTools` opts into framework-provided model-facing tools. Each
-enabled capability materializes as ordinary server tools at discovery
-time, so turns, direct calls, `info`, and the playground treat them
-like authored tools. Authored tools with the same name win, with a
+enabled capability shows up as ordinary server tools, so turns, direct
+calls, `info`, and the playground treat them like authored tools. Authored tools with the same name win, with a
 warning, and like all server tools they run on the local runtime.
 
 `builtinTools: { reminders: true }` adds three tools bound to the
@@ -3873,22 +4278,6 @@ current conversation over `host.reminders`: `reminders_create`,
 continuation key can't arm reminders. See
 [Schedules and reminders](/docs/reference/schedules.md#reminders).
 
-## Generate instructions
-
-When the system prompt must be computed, author `agent/instructions.ts`
-instead of markdown:
-
-```ts
-import { defineInstructions } from "@cursor/july";
-
-export default defineInstructions({
-  markdown: `You are the on-call assistant for ${process.env.TEAM_NAME}.`,
-});
-```
-
-The directory form and the runtime mapping are in
-[Instructions](/docs/reference/instructions.md).
-
 ## Serve programmatically
 
 `serve(dirOrProject, options)` embeds the server in your own process:
@@ -3898,7 +4287,7 @@ import { serve } from "@cursor/july";
 
 const handle = await serve("./my-agent", {
   port: 3000,
-  apiKey: process.env.CURSOR_API_KEY, // optional; see credential order
+  apiKey: process.env.CURSOR_API_KEY,
 });
 console.log(`listening on ${handle.url}`);
 // handle.callTool(...), handle.dispatchSchedule("heartbeat"),
@@ -3907,20 +4296,17 @@ console.log(`listening on ${handle.url}`);
 
 Host settings match the documented [CLI](/docs/reference/cli.md) `serve` flags.
 `serve()` also accepts `discovery` (project-loading options) and
-`mode: "single" | "multi"`. The Cursor credential resolves in one order
-everywhere: explicit `apiKey`, then `CURSOR_API_KEY`, then
-`CURSOR_API_KEY_FILE` (hosted default `/run/cursor/secrets/CURSOR_API_KEY`
-when unset), then `CURSOR_SERVICE_ACCOUNT_KEY`, then the key stored by
-`agent-sdk login`. On a host that has both the service-account key and a
-bind file, the file principal wins.
-
-## What's next
+`mode: "single" | "multi"`. Pass `apiKey` or use the same Cursor
+credential as the CLI: `CURSOR_API_KEY`, `CURSOR_API_KEY_FILE`,
+`CURSOR_SERVICE_ACCOUNT_KEY`, or `agent-sdk login`.
 
-Continue with these pages:
+## Related
 
 - [Instructions](/docs/reference/instructions.md): the required half of a minimal
   agent
 - [CLI](/docs/reference/cli.md): the `serve` flags `serve()` accepts
+- [Sessions](/docs/reference/sessions.md): workspaces, identifiers, and turn admission
+- [Schedules](/docs/reference/schedules.md): reminder tools opted in here
 
 ---
 
@@ -3928,13 +4314,12 @@ Source: /docs/reference/artifacts.md
 
 # Artifacts
 
-An artifact marks a durable output the agent produced: a reviewed PR
-URL, a generated report, a decision record. Sessions come and go;
-artifacts persist across them, capped and listable, so the people
-supervising an agent see what it shipped without replaying event
-streams.
+Artifacts are durable outputs such as reviewed pull requests, reports,
+or decision records. An artifact kind defines the data it accepts, and
+the artifacts API tags or updates records by key. Records persist across
+sessions and can be listed, streamed, or downloaded.
 
-## Declare kinds
+## Artifact kinds
 
 Author `agent/artifacts.ts` with `defineArtifacts` from
 `@cursor/july/artifacts`:
@@ -3955,26 +4340,21 @@ export default defineArtifacts({
 });
 ```
 
-`defineArtifacts` accepts three fields. `kinds` declares the artifact
-kinds: with kinds declared, `tag` accepts only these; with none, any
-kind string is accepted freeform. Each kind's `description` says what it
-holds and doubles as the model-facing prompt for `tag_artifact`. An
-optional Zod `schema` validates payloads before they persist (the parsed
-output is stored, so defaults and coercions apply). `agentTool` exposes
-the model-facing `tag_artifact` tool generated from the kinds registry;
-it requires at least one declared kind. `max` is the retention cap,
-default 1000: on insert past the cap, the oldest-updated artifact is
-evicted.
+| Option | Contract |
+| --- | --- |
+| `kinds` | Map of accepted kind names to a non-empty `description` and optional Zod `schema` |
+| `agentTool` | Expose `tag_artifact` to the model; requires at least one declared kind |
+| `max` | Positive retention cap; defaults to `1000` and evicts the oldest-updated record |
+
+With declared kinds, `tag` rejects any other kind. With no registry, it
+accepts free-form kind names and defaults an omitted kind to
+`"artifact"`. A kind's schema validates `data`, and the parsed value is
+stored, including schema defaults and coercions.
 
-## Tag from host code
+## Tag artifacts from host code
 
-Every handler surface carries `ctx.artifacts` (or `args.artifacts`),
-an `ArtifactsApi` with `tag` and `list`: tools, hooks, channel route
-handlers and `onStart`, schedule `run` handlers, and reminder `run`
-handlers. Tool and hook facades are session-bound, so `tag` auto-fills
-the `sessionId` (and `turnId` when known). Channel, schedule, and
-reminder facades are unbound; pass `sessionId` in the tag input to
-attribute one.
+Tools, hooks, channel handlers, channel `onStart`, schedules, and
+reminders receive an `ArtifactsApi` with `tag` and `list`.
 
 ```ts
 await ctx.artifacts.tag({
@@ -3985,59 +4365,66 @@ await ctx.artifacts.tag({
 });
 ```
 
-`key` is the upsert handle: tagging the same key again replaces the
-record instead of creating a new one, so re-reviewing a PR updates one
-row. A `contents` payload (string or bytes, with an optional
-`contentType`) attaches a file or blob served at
-`GET /v1/artifacts/:id/content`; re-tagging a keyed artifact without
-`contents` keeps the existing payload.
+| Tag field | Contract |
+| --- | --- |
+| `data` | Required JSON data, validated when the kind has a schema |
+| `kind` | Declared or free-form kind |
+| `key` | Agent-wide upsert key; the same key updates one record across kinds |
+| `title` | Optional display title |
+| `contents` | String or bytes served by the content route |
+| `contentType` | MIME type for `contents` |
+| `sessionId`, `turnId` | Attribute the artifact to a session or turn |
+| `source` | `"host"` or `"model"`; defaults to `"host"` |
+
+Tool, hook, result, and channel-event contexts are session-bound, so
+they fill `sessionId` and the current `turnId`. Channel routes,
+`onStart`, schedules, and reminders receive an unbound facade; pass
+`sessionId` to attribute an artifact.
+
+Re-tagging a key without `contents` keeps its file or blob when the
+`sessionId` stays the same. Rebinding the key to another session without
+new contents removes the previous payload. `tag` returns the stored
+`ArtifactRecord`.
+
+| Record field | Contract |
+| --- | --- |
+| `id` | Stable ID derived from `key`, or a generated ID when no key is set |
+| `kind`, `data` | Validated kind and JSON payload |
+| `key`, `title` | Optional upsert key and display title |
+| `content` | Optional `{ size, contentType? }` metadata |
+| `sessionId`, `turnId` | Optional session attribution |
+| `source` | `"host"` or `"model"` |
+| `createdAt`, `updatedAt` | ISO-8601 timestamps |
 
-## Let the model tag
+## Expose `tag_artifact` to the model
 
 With `agentTool: true`, the `tag_artifact` server tool materializes from
-the kinds registry. Its description tells the model to tag notable
-outputs and lists each kind with its description, and its input schema
-is a discriminated union over the declared kinds, so a schema'd kind is
-validated exactly like a host-side tag. An authored tool named
-`tag_artifact` shadows the built-in, with a warning.
+the kinds registry. Its input accepts the declared kinds and validates
+their data with the same schemas as host-side tagging. The kind
+descriptions tell the model which output each one represents.
 
-## Observe and list
+An authored tool named `tag_artifact` takes precedence over the generated
+tool.
 
-Tagging emits an `artifact.tagged` event on the attributed session's
-stream, carrying the record: `id`, `kind`, `key`, `title`, `data`, and
-`source` (`"host"` for host code, `"model"` for `tag_artifact`). Hooks,
-channel `events`, and evals see it like any other
-[stream event](/docs/reference/sessions.md#which-events-can-i-stream).
+## List artifacts
 
-Over HTTP:
+`list({ kind?, sessionId? })` returns matching records newest-updated
+first. HTTP callers can list records and download content through the
+[artifact routes](/docs/reference/http-api.md#list-and-download-artifacts).
 
-```bash
-curl 'http://127.0.0.1:3000/<slug>/v1/artifacts?kind=reviewed-pr&limit=20'
-curl 'http://127.0.0.1:3000/<slug>/v1/artifacts/<id>/content'
-```
+## Stream artifact tags
 
-`GET /v1/artifacts` returns records newest-updated first, filterable by
-`kind` and `sessionId`. Session ownership applies, same as
-`/v1/sessions`. The playground renders tagged artifacts too.
+Tagging an artifact with a `sessionId` emits `artifact.tagged` on that
+session. Its event data contains `id`, `kind`, `key`, `title`, `data`,
+and `source`. See [Stream events](/docs/reference/sessions.md#stream-events) for the
+event envelope.
 
-## Gate evals on tagging
-
-`t.taggedArtifact(kind?, predicate?)` gates an eval on at least one
-artifact tagged during the test turn, optionally of one kind and
-matching a predicate over the record:
-
-```ts
-t.taggedArtifact("reviewed-pr", (record) => record.source === "model");
-```
-
-## What's next
-
-Continue with these pages:
+## Related
 
-- [Sessions and streaming](/docs/reference/sessions.md): the `artifact.tagged` event
-  in the full vocabulary
-- [Tools](/docs/reference/tools.md): the `ctx` that carries `artifacts`
-- [Evals](/docs/evals.md): the assertions `taggedArtifact` sits beside
+- [Sessions](/docs/reference/sessions.md)
+- [Tools](/docs/reference/tools.md)
+- [Evals](/docs/reference/evals.md)
+- [HTTP API](/docs/reference/http-api.md)
 
 ---
 
@@ -4045,24 +4432,21 @@ Source: /docs/reference/channels.md
 
 # Channels
 
-A channel is the surface an agent lives on. The built-in HTTP session
-channel is always mounted. Custom channels declare their own routes
-under `/v1/channels/<id>`. The Slack and GitHub packs are prebuilt
-channels with platform transports. GitLab and Bitbucket packs cover their
-hosted and self-managed products. This page is the authoring reference;
-for the walkthrough, see the [Webhooks guide](/docs/guides/webhooks.md).
+A channel connects an external surface to agent sessions. A file at
+`agent/channels/<id>.ts` defines channel `<id>` and mounts its routes
+under `/v1/channels/<id>`. The built-in HTTP session channel is always
+available alongside any custom or prebuilt channels.
 
 ## Built-in HTTP channel
 
-It's always mounted, under `/<slug>` in the default multi-agent layout:
-session create, follow-up, stream, stop, the sessions list, approvals,
-deterministic tool calls, health, and info. For the route-by-route
-contract, see the [HTTP API reference](/docs/reference/http-api.md).
+The built-in channel serves the session, approval, tool, discovery, and
+health routes. In a multi-agent host, each agent's routes sit under its
+slug. See the [HTTP API](/docs/reference/http-api.md) for request and response
+contracts.
 
 ## Define a custom channel
 
-Author `agent/channels/<id>.ts`. The filename is the channel id and the
-route prefix:
+Use `defineChannel` with one or more typed routes:
 
 ```ts
 import { defineChannel, POST } from "@cursor/july/channels";
@@ -4075,237 +4459,173 @@ export default defineChannel({
       bodySchema: z.object({
         message: z.string(),
         prUrl: z.string().url(),
-        thread: z.string().optional(),
       }),
-      handler: async (_req, { callTool, send, body }) => {
-        const prepared = await callTool("inspect_pr", {
-          prUrl: body.prUrl,
-        });
-        if (prepared.isError) {
-          return Response.json(
-            { error: prepared.errorMessage ?? "Could not inspect pull request" },
-            { status: 502 }
-          );
-        }
-
+      handler: async (_request, { send, body }) => {
         const session = await send(
-          `${body.message}\n\nRead pr.json before answering.`,
+          `${body.message}\n\nPull request: ${body.prUrl}`,
           {
-            continuationToken: body.thread ?? `pr:${body.prUrl}`,
-            workspaceFiles: {
-              "pr.json": JSON.stringify(prepared.result, null, 2) ?? "null",
-            },
+            continuationToken: `pr:${body.prUrl}`,
           }
         );
         return Response.json({ sessionId: session.id });
       },
     }),
   ],
-  events: {
-    "message.completed"(event, channel, ctx) {
-      // deliver the reply to the surface that owns this channel
-    },
-  },
-  // auth: [...], state: {...}, onStart(...), onStop(...)
 });
 ```
 
-This example assumes `agent/tools/inspect_pr.ts` exists. The handler
-calls it before the model turn, so every review starts with validated PR
-data. It also derives a stable conversation key from the PR URL and
-writes the tool result to `pr.json`. Instructions can ask the model to
-inspect a PR, but host code guarantees it.
+The route above is
+`POST /v1/channels/<id>/review`. Calls for the same pull request reuse
+one conversation because they pass the same continuation token.
 
 ## Route verbs and schemas
 
-`GET`, `POST`, `PUT`, `PATCH`, and `DELETE` helpers build routes. Their
-schemas are Zod, enforced at compile time:
+Route paths must begin with `/`. The method helper determines which Zod
+schemas the route accepts:
 
-| Verb                     | Required schema                       |
-| ------------------------ | ------------------------------------- |
-| `GET`                    | `querySchema`                         |
-| `POST` / `PUT` / `PATCH` | `bodySchema` (optional `querySchema`) |
-| `DELETE`                 | both optional                         |
+| Helper | Schema contract |
+| --- | --- |
+| `GET` | `querySchema` is required |
+| `POST`, `PUT`, `PATCH` | `bodySchema` is required; `querySchema` is optional |
+| `DELETE` | Both schemas are optional |
 
-Plain JSON Schema objects won't type-check; use `z.object({})` or
-`z.unknown()` for intentionally open surfaces. The host validates before
-the handler runs. Handlers receive typed `args.body` and `args.query`,
-and empty POST bodies are coerced to `{}` first. Declared schemas are
-projected on `GET /v1/info`, which powers the playground's **Try**
-buttons and composer **slash commands**.
+Plain JSON Schema objects don't type-check. Use `z.object({})` or
+`z.unknown()` for an open surface. The host validates the body and query
+before calling the handler, returning `400` on failure; an empty body is
+read as `{}`. Declared schemas also appear in `GET /v1/info` for
+playground requests and slash commands.
 
 ## Handler arguments
 
-Handlers receive the Fetch `Request` and an args object:
-
-| Member                              | What it is                                                                                                                                                                                                                                                                                  |
-| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `send(message, options?)`           | Run a model turn on this channel; returns the session handle (options below)                                                 |
-| `getSession(sessionId)`             | Look up an existing session on this channel                                                                                  |
-| `receive(channelDefinition, input)` | Hand off to another channel (schedules use this)                                                                             |
-| `callTool(name, input, options?)`   | Deterministic server-tool call ([Tools](/docs/reference/tools.md#call-a-tool-without-a-model-turn))                                        |
-| `body`, `query`, `params`           | Validated payloads and `:param` path segments                                                                                |
-| `auth`                              | The `AuthContext` resolved by this route's auth chain                                                                        |
-| `requestIp`                         | The TCP peer address                                                                                                         |
-| `host`                              | Shared services: `host.mcp`, `host.github`, `host.slack`, `host.kv`, `host.files`, `host.reminders`                          |
-| `waitUntil(promise)`                | Background work that outlives the response                                                                                   |
-| `sessionUrls(request, sessionId)`   | Absolute playground + trace URLs for a session on this mount                                                                 |
-| `artifacts`                         | Unbound [artifacts](/docs/reference/artifacts.md) facade; pass `sessionId` in `tag` input to attribute one                                 |
-
-`send` options: `continuationToken` (the conversation key),
-`admission` (`"preempt"` interrupts a busy session, the default;
-`"coalesce"` enqueues behind the running turn, the
-[Slack policy](/docs/reference/sessions.md#what-happens-when-i-send-a-follow-up)),
-`workspaceFiles`, `workspaceDir`, `cloud` (attach cloud repos for this
-session), `auth` (defaults to the request principal), `state` (starting
-channel state for new sessions), `title` (session display title), and
-`purpose` (`"eval"` marks the session as regression traffic).
+Each handler receives the Fetch `Request` and a typed arguments object.
+
+| Member | Contract |
+| --- | --- |
+| `send(message, options?)` | Start or resume a session on this channel |
+| `getSession(sessionId)` | Return this channel's session, or `null` |
+| `receive(channel, input)` | Hand work to another channel |
+| `callTool(name, input, options?)` | [Call a server tool](/docs/reference/tools.md#call-a-tool-without-a-model-turn) without a model turn |
+| `body`, `query`, `params` | Validated inputs and `:param` path segments |
+| `auth` | The `AuthContext` returned by the route's auth chain |
+| `requestIp` | The TCP peer address, or `null` |
+| `host` | Shared MCP, provider, storage, telemetry, and reminder services |
+| `waitUntil(promise)` | Track work after the response returns |
+| `sessionUrls(request, sessionId)` | Build absolute playground and trace URLs for this mount |
+| `artifacts` | List or tag [artifacts](/docs/reference/artifacts.md); pass `sessionId` when attributing one |
+
+### `send` options
+
+| Option | Contract |
+| --- | --- |
+| `continuationToken` | Resume the session with this channel-local key, or create one when the key is new |
+| `admission` | `"preempt"` interrupts a busy turn; `"coalesce"` queues behind it. The default is `"preempt"` |
+| `workspaceFiles` | Add relative files for the next turn |
+| `workspaceDir` | Use an absolute local working directory |
+| `cloud` | Override cloud session options when creating a session |
+| `auth` | Set the session principal; defaults to the request principal |
+| `state` | Set starting channel state for a new session |
+| `title` | Set the display title for a new session |
+| `purpose` | Use `"eval"` to mark a new session as regression traffic |
+| `dryRun` | Run read tools and stub write tools for a new session |
+| `asOf` | Freeze a new session at an ISO-8601 instant with a timezone |
+
+`send` returns a `ChannelSession`. Its `id` identifies the session,
+`continuationToken` contains its current channel key, and `isNew` says
+whether this call created it. A coalesced call also returns
+`coalesced: true`.
 
 ## Events
 
 The `events` map subscribes the channel to stream events for the
 sessions it owns. Keys are event types from the
-[event vocabulary](/docs/reference/sessions.md#which-events-can-i-stream), or `"*"`.
-Handlers receive `(event, channel, ctx)`, where `channel.state` is the
-per-session adapter state, `ctx.session` is the session info, and
-`ctx.host` is the shared host services, bound to that session as in a
-[hook](/docs/reference/hooks.md#handler-context). This is where a channel delivers
-replies back to its surface.
-
-## State and lifecycle
-
-`state` declares the starting per-session adapter state (JSON), persisted
-on the session record. Routes and event handlers read and mutate it
-through `channel.state`. `onStart(args)` runs when the channel mounts.
-`onStop()` runs when the server stops.
-
-`onStart` receives the route helpers (`send`, `getSession`, `receive`,
-`callTool`, `host`, `waitUntil`, `artifacts`, `logger`) plus helpers
-for long-lived transports:
-
-- `emitAssistantMessage(sessionId, text)` appends an assistant message
-  without a model turn, for host tasks that already produced the final
-  text.
-- `hasContinuationSession(token)` and `isContinuationBusy(token)`
-  report whether a continuation token has a live session and whether a
-  turn is in flight on it.
-- `interruptContinuation(token)` stops the in-flight turn and clears
-  coalesced follow-ups queued behind it.
-- `resolveApproval(sessionId, callId, decision, auth, options?)`
-  approves or denies a parked tool call, how Slack Block Kit buttons
-  unblock a turn without the HTTP approvals route.
+[event vocabulary](/docs/reference/sessions.md#stream-events), or `"*"`. Each handler
+receives `(event, channel, ctx)`, including the session's
+`channel.state`, session info, and shared host services. Use these
+handlers to deliver progress and replies to the surface that owns the
+channel.
 
-## Auth policies
+## Session state
+
+`state` on the channel definition supplies starting JSON for each new
+session. A route can instead pass `state` to `send`; event handlers read
+and update the active value through `channel.state`.
+
+## Start and stop a channel
 
-Every route runs an auth-policy chain: the channel's `auth` array, or
-`[localDevStrict()]` when unset. A policy is a function
-`(request, info) => AuthContext | null` (async allowed); the first
-non-null wins, and a request no policy admits gets `401`.
+`onStart(args)` runs when the channel mounts, and `onStop()` runs when
+the host stops. `onStart` receives the route helpers plus these
+transport controls:
 
-| Policy              | Admits                                                                                                                                                                                                                                                                                                                                                     |
-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `localDevStrict()`  | Direct loopback callers with no proxy-forwarding headers (`X-Forwarded-For`, `X-Real-IP`, `Forwarded`, and `X-Forwarded-Host` are all rejected, so tunnels and same-host reverse proxies don't silently re-expose the route), plus a loopback `Host` header, which rejects DNS-rebinding callers that reach 127.0.0.1 with a remote hostname. |
-| `localDev()`        | Like `localDevStrict()` but without the `Host` check. An explicit, weaker opt-in.                                                                                                                                                                                                                                                                          |
-| `loopbackOnly()`    | A loopback TCP peer, ignoring forwarding headers; for dev relays that legitimately carry them, like `gh webhook forward`.                                                                                                                                                                                                                                  |
-| `bearerAuth(token)` | `Authorization: Bearer <token>`, compared in constant time. Also accepts a verifier function mapping a presented token to an `AuthContext`.                                                                                                                                                                                                                |
-| `allowAll()`        | Everyone, as an `anonymous` principal. Only for surfaces protected upstream (an HMAC-verified webhook) or intentionally public.                                                                                                                                                                                                                            |
-| `publicEndpoint()`  | Everyone on this custom channel. Managed hosting also serves the channel without an alias token. Use it only when the handler verifies the provider signature.                                                                                                                                                                                             |
+| Helper | Contract |
+| --- | --- |
+| `emitAssistantMessage(sessionId, text)` | Append final assistant text without starting a model turn |
+| `hasContinuationSession(token)` | Check whether a token maps to a session |
+| `isContinuationBusy(token)` | Check whether a turn is active for a token |
+| `interruptContinuation(token)` | Stop the active turn and clear queued coalesced follow-ups |
+| `resolveApproval(...)` | Approve or deny a parked tool call |
+
+## Auth policies
 
-`publicEndpoint()` applies only to custom channel routes. It does not open
-the built-in session or tool API.
+Every route runs the channel's `auth` array. The default is
+`[localDevStrict()]`. Policies may be asynchronous; the first one to
+return an `AuthContext` admits the request, and an all-null result
+returns `401`.
+
+| Policy | Admits |
+| --- | --- |
+| `localDevStrict()` | Direct loopback requests with a loopback hostname and no proxy-forwarding headers |
+| `localDev()` | Direct loopback requests with no proxy-forwarding headers, without checking the hostname |
+| `loopbackOnly()` | Any loopback TCP peer, including local relays that carry forwarding headers |
+| `bearerAuth(tokenOrVerify)` | A matching bearer token, or a token accepted by the verifier |
+| `sharedSecretAuth({ header, secret })` | A header matching the named environment or deployment secret |
+| `hmacSignatureAuth({ header, secret, prefix? })` | A hex HMAC-SHA256 signature over the raw body using the named secret |
+| `allowAll()` | Every caller as an anonymous principal |
+| `publicEndpoint()` | Every caller on this custom channel; managed hosting also exposes the route without an alias token |
+
+Use `allowAll()` only for an intentionally public surface or one
+protected upstream. With `publicEndpoint()`, the handler must verify the
+provider's signature. The policy applies only to custom channel routes;
+it doesn't open the built-in session or tool API.
 
 The resolved `AuthContext` (`{ authenticator, principalId,
 principalType, attributes? }`) becomes the request principal. Sessions
-bind to the principal that created them, and follow-up, stream, and list
-routes enforce ownership (`403` otherwise).
+belong to the principal that created them, and other principals receive
+`403` on owned routes.
 
 Server flags interact with authored auth: `--bearer-token` swaps the
 default `localDevStrict()` for `bearerAuth(...)` on channels that don't
 author their own chain, and `--allow-anonymous` swaps it for
-`allowAll()`. Authored `auth` arrays always win over both. A channel that
-declares `[localDevStrict()]` stays loopback-only even on an
-`--allow-anonymous` host.
-
-## First class channels
-
-**Slack** (`@cursor/july/channels/slack`): Socket Mode
-transport, streaming replies, engagement rules, approval cards, and a
-default block on Slack Connect / guest / other-workspace senders. Author
-`agent/channels/slack.ts` with `slackChannel()`. Guide:
-[Slack](/docs/guides/slack.md).
-
-**GitHub** (`@cursor/july/channels/github`): webhook dispatch
-with signature verification, per-event hooks returning `{ auth }` (a
-model turn), `{ task }` (host work), or `null`, and CLI tooling for
-replay and live forwarding. Author `agent/channels/github.ts` with
-`githubChannel()`. Opt-in `progress.commitStatus` and `progress.banner`
-converge a merge-box check and sticky PR comment from default stream
-events. Supports GitHub.com and GitHub Enterprise Server. Guide:
-[GitHub](/docs/guides/github.md).
-
-**GitLab** (`@cursor/july/channels/gitlab`): verified project hooks for
-merge requests, notes, pipelines, pushes, and custom event types. Supports
-GitLab.com and self-managed GitLab. Author `agent/channels/gitlab.ts` with
-`gitlabChannel()`. Guide: [GitLab](/docs/guides/gitlab.md).
-
-**Bitbucket** (`@cursor/july/channels/bitbucket`): verified repository hooks
-for pull requests, comments, pushes, and custom event types. Supports
-Bitbucket Cloud and Bitbucket Data Center through one normalized hook API.
-Author `agent/channels/bitbucket.ts` with `bitbucketChannel()`. Guide:
-[Bitbucket](/docs/guides/bitbucket.md).
-
-**Deployments** (`@cursor/july/channels/deployments`): pull deploy
-events. Declare `events` and handle each one in `onEvent`. Each event
-carries `deploySourceUri` and `deployVersion`. Author
-`agent/channels/deployments.ts` with `deploymentsChannel()`.
-
-On Cursor-managed hosting, omit `deploySourceUris`. The deployment's
-watched repositories bind the event scope automatically. Name sources
-to narrow the scope or to drive the self-hosted pull relay. Subscribe
-per deploy source with `deploySourceUris` and narrow with `environments`
-or `events`. Each entry must match `Deployment.deploy_source_uri` as
-your deployment writer records it. Matching is case-insensitive but
-otherwise literal. It uses the host credential. A restart resumes
-rather than dropping events. An empty `deploySourceUris` list mounts the
-channel but starts no pull, so an env-configured agent stays inert until
-its deploy sources are set.
-
-**Change Monitors** (`@cursor/july/channels/change-monitors`): Change
-Monitor Checkpoint events. The channel publishes Factory
-`checkpoint.created` for every Checkpoint create. The agent filters the
-result (for example to the `issues` arm). The payload contains the
-full Checkpoint resource. This channel is scoped to Change Monitors,
-not generic Factory Checkpoints. There is no repository filter or
-resource filter. Author `agent/channels/change-monitors.ts` with
-`changeMonitorsChannel()`. It uses the host credential.
-
-**Issues** (`@cursor/july/channels/issues`): Factory issue events.
-The channel publishes `issue.created` for every Issue create. The
-agent filters if it needs a subset. The payload contains the full
-Issue resource. There is no repository filter or resource filter.
-Author `agent/channels/issues.ts` with `issuesChannel()`. It uses the
-host credential.
+`allowAll()`. An authored `auth` array always takes precedence.
 
-For other platforms like Discord or Teams, use the authored
-`defineChannel` webhook form.
+## Prebuilt channels
 
-## Continuation semantics
+| Import | Factory | Surface |
+| --- | --- | --- |
+| `@cursor/july/channels/slack` | `slackChannel()` | Slack messages, threads, streaming replies, and approvals. See [Slack](/docs/guides/slack.md) |
+| `@cursor/july/channels/github` | `githubChannel()` | GitHub and GitHub Enterprise webhooks. See [GitHub](/docs/guides/github.md) |
+| `@cursor/july/channels/gitlab` | `gitlabChannel()` | GitLab.com and self-managed GitLab hooks. See [GitLab](/docs/guides/gitlab.md) |
+| `@cursor/july/channels/bitbucket` | `bitbucketChannel()` | Bitbucket Cloud and Data Center hooks. See [Bitbucket](/docs/guides/bitbucket.md) |
+| `@cursor/july/channels/deployments` | `deploymentsChannel()` | Deployment events filtered by source, environment, or event name |
+| `@cursor/july/channels/change-monitors` | `changeMonitorsChannel()` | Change Monitor `checkpoint.created` events |
+| `@cursor/july/channels/issues` | `issuesChannel()` | Factory `issue.created` events |
 
-Channels own their continuation-token format. The built-in HTTP channel
-mints opaque rotating tokens, Slack uses `channelId:threadTs`, and PR
-automations use keys like `pr:owner/repo#N`. Same token, same durable
-session; one active continuation per session; the HTTP channel returns
-`409` for stale tokens. For the full session model, see
-[Sessions](/docs/reference/sessions.md).
+For other platforms like Discord or Teams, use the authored
+`defineChannel` route form.
 
-## What's next
+## Continuation tokens
+
+Each channel defines its continuation-token format. The same token
+resumes the same conversation; the built-in HTTP channel rotates its
+opaque token after every accepted follow-up and returns `409` for a
+stale token. See [Session identifiers](/docs/reference/sessions.md#session-identifiers)
+for the full contract.
 
-Continue with these pages:
+## Related
 
-- [Webhooks guide](/docs/guides/webhooks.md): the same API, walked through
-- [HTTP API](/docs/reference/http-api.md): session, discovery, and channel routes
-- [Sessions and streaming](/docs/reference/sessions.md): the events channels
-  subscribe to
+- [Webhooks](/docs/guides/webhooks.md)
+- [HTTP API](/docs/reference/http-api.md)
+- [Sessions](/docs/reference/sessions.md)
+- [Hooks](/docs/reference/hooks.md)
 
 ---
 
@@ -5281,19 +5601,18 @@ These environment variables affect the CLI and its channel packs.
 
 Source: /docs/reference/connections.md
 
-# MCP Connections
+# MCP connections
 
-An MCP connection gives the agent tools from an MCP server. One file per
-server under `agent/mcp-connections/`, and the filename becomes the server
-name the model sees. An MCP connection default-exports `defineConnection`
-from `@cursor/july/connections`, and the transport comes in
-four shapes: remote HTTP, local stdio, the signed-in Cursor account's
-connectors, and peer agents on the same host.
+An MCP connection gives the agent tools from an MCP server. Define one
+file per server under `agent/mcp-connections/`; the filename becomes the
+server name. Default-export `defineConnection` from
+`@cursor/july/connections`. The transport is remote HTTP, local stdio,
+the signed-in Cursor account's connectors, or a peer agent on the same
+host.
 
-Put a server in `agent/host-connections/` when host tools should call it
-and the model should not. Same `defineConnection` shape. `agent-sdk mcp
-oauth` still works. The playground and the turn's MCP servers never see
-those files.
+Put a server in `agent/host-connections/` when only host tools should
+call it. Host connections use the same `defineConnection` shape and
+support `agent-sdk mcp oauth`; the model and playground don't see them.
 
 ## Remote MCP server
 
@@ -5315,8 +5634,7 @@ Tokens come from env vars. Never hardcode them in the file.
 For servers that speak OAuth, set `oauth: true` and authorize with the
 CLI or mid-run Connect. Tokens live in `mcp-auth.json` under the CLI
 config directory. `--store` copies them onto the deployment as
-`MCP_OAUTH_<NAME>_*` secrets. Hosted Connect lets the current
-process retry.
+`MCP_OAUTH_<NAME>_*` secrets.
 
 ```ts
 export default defineConnection({
@@ -5328,24 +5646,17 @@ export default defineConnection({
 ```bash
 agent-sdk mcp oauth inventory           # browser PKCE → local mcp-auth.json
 agent-sdk mcp oauth inventory --store   # also upsert deployment secrets
-# Hosted Connect retries this process. Self-hosted stays file-only.
 ```
 
 Full walkthrough: [Host MCP OAuth](/docs/guides/mcp-oauth.md). Companion
 skill: [`skills/mcp-auth/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/mcp-auth/SKILL.md).
 
-Account MCP (`cursorAccount: true`) is the right choice for connectors
-already linked in the Cursor dashboard. Omit `servers` (or pass `"*"`)
-to forward every connected connector. If the model should call those
-tools by name on local turns, set `advertiseTools: true`.
+## Per-session auth
 
-## Per-session auth (`auth`)
-
-For http/sse connections whose credential depends on **who the session is
-for** (a multi-tenant agent asserting the tenant it is acting for),
-declare an `auth` callback instead of static headers. It runs host-side
-at turn-build time with the session's `SessionInfo` and returns headers
-merged over the static ones:
+For http/sse connections whose credential depends on who the session is
+for, declare an `auth` callback instead of static headers. It runs
+host-side with the session's `SessionInfo` and returns headers merged
+over the static ones:
 
 ```ts
 export default defineConnection({
@@ -5353,39 +5664,31 @@ export default defineConnection({
   auth: async (session) => ({
     headers: { Authorization: `Bearer ${await grantFor(session)}` },
   }),
-  advertiseTools: true, // optional — named tools instead of meta-tools
+  advertiseTools: true,
 });
 ```
 
-The callback is evaluated on **every local turn**, including reminder
-fires and post-restart follow-ups, so the identity always comes from the
-session itself, never from state parked in memory. The model never sees a
-tenant parameter and can never choose the tenant. A callback that throws
-fails the turn: a turn never silently runs without the connection's
-identity. Local runtime only; cloud turns are refused. `host.mcp` calls
-from server tools keep the static headers only. Not combinable with
-`oauth: true`; the host OAuth provider owns the Authorization header.
+The identity always comes from the session itself, never from a tenant
+parameter the model could invent. A callback that throws fails the
+turn; a cloud turn with `auth` is refused instead of running without
+that identity. `host.mcp` calls from server tools keep the static
+headers only. You can't combine `auth` with `oauth: true`.
 
 Derive the identity from durable session facts: `session.auth`,
-`session.id`, or your channel's own session state. Do **not** key it off
-`session.continuationKey`: the HTTP channel rotates the continuation key
-after every accepted follow-up, so a tenant mapping keyed on it silently
-breaks mid-conversation. (Channels that mint stable, parseable tokens by
-design are the exception.)
-
-`auth` works attached or advertised. Advertised connections open
-per-operation clients with the evaluated headers. Attached connections
-ride the turn's SDK `mcpServers`, passed on **every send** rather than
-pinned on the cached per-session agent handle, so a rotated credential is
-live on the very next turn. A stateful stdio server cannot share a
-process with an attached `auth` connection. Advertise the auth
-connection instead.
-
-## Advertise a connection's tools by name (`advertiseTools`) {#advertise-tools}
-
-Set `advertiseTools: true` when the model should call an MCP server's tools
-by name. The Agent SDK preserves each tool's name, description, input and
-output schemas, and MCP annotations.
+`session.id`, or your channel's own session state. Do not key it off
+`session.continuationKey`. The HTTP channel rotates that key after every
+accepted follow-up, so a tenant mapping keyed on it breaks
+mid-conversation.
+
+`auth` works attached or advertised. Advertise the auth connection
+instead of attaching it next to a stateful stdio server.
+
+## Advertise tools {#advertise-tools}
+
+Set `advertiseTools: true` when the model should call an MCP server's
+tools by name. The Agent SDK preserves each tool's description, input
+and output schemas, and MCP annotations. Exposed names normalize invalid
+characters and add numeric suffixes to avoid collisions.
 
 ```ts
 export default defineConnection({
@@ -5395,20 +5698,22 @@ export default defineConnection({
 });
 ```
 
-A listing failure, invalid tool name, or name collision fails the turn.
-Advertised tools follow the same runtime support as server tools. They cannot
-be called through the direct tool API.
+A listing or authentication failure fails the turn by default. Set
+`optional: true` to omit an unavailable connection instead. Advertised
+tools follow the same runtime support as server tools, and [direct tool
+calls](/docs/reference/tools.md#call-a-tool-without-a-model-turn) use the same names.
 
-In a dry-run session, MCP tools marked read-only run normally. Tools marked
-as writes are stubbed. Tools without effect annotations are unavailable.
+In a dry-run session, MCP tools marked read-only run normally. Tools
+marked as writes are stubbed. Tools without effect annotations are
+unavailable.
 
-## Restrict which tools a connection serves
+## Filter connection tools
 
 Use `tools` the same way you allowlist harness tools on the agent. When
 set, the connection serves only those names. Use `disallowedTools` to
-drop names instead. The two combine as deny-wins, same as the Cursor
-SDK. The model and `host.mcp` only see what remains. On a model-visible
-connection, set `advertiseTools: true` so the raw server is not attached.
+drop names instead. The two combine as deny-wins. The model and
+`host.mcp` only see what remains. A model-visible filter requires
+`advertiseTools: true`.
 
 ```ts
 export default defineConnection({
@@ -5416,7 +5721,9 @@ export default defineConnection({
   advertiseTools: true,
   tools: ["search_skus", "get_stock"],
 });
+```
 
+```ts
 export default defineConnection({
   url: "https://mcp.example.com/inventory",
   advertiseTools: true,
@@ -5425,9 +5732,9 @@ export default defineConnection({
 ```
 
 Names are the server's `tools/list` names. Unknown names are omitted. A
-filter that matches nothing on the server fails the turn. Combine with
-`effects: "read"` to keep only the listed tools the server classifies as
-reads.
+filter that matches nothing on the server fails the turn unless
+`optional: true`. Combine with `effects: "read"` to keep only the listed
+tools the server classifies as reads.
 
 A list of names is an allowlist. An object of handlers authors TypeScript
 tools. On `host-connections/`, a name list restricts `host.mcp` without
@@ -5445,12 +5752,8 @@ export default defineConnection({
 });
 ```
 
-This suits small purpose-built servers, like a `units` converter
-shipped next to the agent.
-
-To run TypeScript in the agent environment (including a repo-less cloud
-VM), author the tools on the connection instead. The Agent SDK packages
-them as stdio MCP. You write `execute`. The Agent SDK speaks the protocol.
+To run TypeScript in the agent environment, including a repo-less cloud
+VM, author the tools on the connection instead. You write `execute`:
 
 ```ts
 export default defineConnection({
@@ -5468,12 +5771,12 @@ export default defineConnection({
 ## Cursor account MCP connection
 
 `{ cursorAccount: true }` forwards the MCP connectors the signed-in
-Cursor account already authorized (dashboard → MCP): Linear, Notion,
-Slack, and the rest. You don't configure tokens. Every tool runs on the
+Cursor account already authorized (dashboard → MCP), such as Linear,
+Notion, and Slack. You don't configure tokens. Every tool runs on the
 Cursor backend with the account's stored OAuth credentials, so raw
-tokens never reach the serve host, session workspaces, or traces.
+tokens never reach the serving host, session workspaces, or traces.
 
-By default the agent gets **every** connected HTTP/SSE connector on the
+By default the agent gets every connected HTTP/SSE connector on the
 account. Pass `servers: "*"` (or `["*"]`) for the same all-connectors
 behavior in an explicit form. Pass a name list when you want a smaller
 set.
@@ -5484,12 +5787,9 @@ export default defineConnection({
   cursorAccount: true,
   advertiseTools: true,
 });
-// same, spelled out:
-export default defineConnection({
-  cursorAccount: true,
-  servers: "*",
-  advertiseTools: true,
-});
+```
+
+```ts
 // only Linear:
 export default defineConnection({
   cursorAccount: true,
@@ -5500,17 +5800,15 @@ export default defineConnection({
 
 Name the file `account.ts`. `cursor.ts` collides with the IDE `cursor`
 MCP namespace. `advertiseTools: true` puts connector tools on local
-turns by name. Without it they sit behind harness meta-tools.
+turns by name.
 
 The host must be signed in (`agent-sdk login`, `CURSOR_API_KEY`, or
-`CURSOR_SERVICE_ACCOUNT_KEY`).
-`serve` fails fast at startup otherwise, and logs each connector's live
-status (`connected`, `needsAuth`, `error`) as it starts.
+`CURSOR_SERVICE_ACCOUNT_KEY`). `serve` fails at startup otherwise.
 
 Filtered account connections work on managed cloud deployments. A
-self-hosted cloud agent with a concrete `servers` list needs `--public-url`.
-Serve fails instead of ignoring the filter. Use a `{ command }` connection
-for stdio servers.
+self-hosted cloud agent with a concrete `servers` list needs
+`--public-url`. Serve fails instead of ignoring the filter. Use a
+`{ command }` connection for stdio servers.
 
 > [!CAUTION]
 > Whoever can talk to the agent can drive these connectors, because they
@@ -5520,11 +5818,11 @@ for stdio servers.
 > for example an SSO proxy or the hosted alias token). Prefer
 > `--bearer-token` on shared hosts.
 
-## Peer MCP connection
+## Peer MCP connection {#peer-mcp-connection}
 
 `{ agent: "<slug>" }` addresses another agent mounted on the same serve
-host. The model gets the peer's `ask` and `check` (and `call_tool`)
-tools and can delegate work to it:
+host. The model gets the peer's `ask` and `check` tools, plus
+`call_tool` when the peer has server tools, and can delegate work to it:
 
 ```ts
 export default defineConnection({
@@ -5534,65 +5832,53 @@ export default defineConnection({
 ```
 
 Unknown slugs and self-references fail `serve` at startup. Walkthrough:
-[Agent-to-agent](/docs/guides/agent-to-agent.md#how-do-i-wire-two-agents).
-
-## Every model-visible MCP connection is available in three places
-
-A file under `agent/mcp-connections/` serves three consumers. Host
-connections skip the first one.
-
-1. **Cursor agent:** Attached connections ride SDK `mcpServers` behind
-   harness MCP meta-tools. Set `advertiseTools: true` so local turns see
-   named tools.
-2. **Server tools:** Deterministic host code composes MCP calls
-   through `ctx.host.mcp`:
-
-   ```ts
-   export default defineTool({
-     description: "Search Linear issues.",
-     inputSchema: z.object({ query: z.string() }),
-     async execute({ query }, ctx) {
-       return ctx.host.mcp.callTool("linear", "list_issues", { query });
-     },
-   });
-   ```
-
-3. **Channel and schedule handlers:** Webhooks hit MCP servers with no
-   model turn at all, through `args.host.mcp`:
-
-   ```ts
-   POST("/sync", {
-     bodySchema: z.object({}),
-     handler: async (_req, { host }) => {
-       const result = await host.mcp.callTool("linear", "list_issues", {});
-       return Response.json(result);
-     },
-   });
-   ```
-
-The host registry is small: `host.mcp.names()` lists MCP connection names,
-and `listTools(name)` / `callTool(name, tool, args)` open the client
-lazily on first use.
+[Peer agents](/docs/guides/agent-to-agent.md#delegate-a-question-to-a-specialist).
 
-## What's next
+## Call MCP from host code
+
+A file under `agent/mcp-connections/` is available to the Cursor agent,
+to server tools through `ctx.host.mcp`, and to channel and schedule
+handlers through `args.host.mcp`. Host connections skip the model.
+
+```ts
+// agent/tools/search_linear.ts
+import { defineTool } from "@cursor/july/tools";
+import { z } from "zod";
 
-Continue with these pages:
+export default defineTool({
+  description: "Search Linear issues.",
+  inputSchema: z.object({ query: z.string() }),
+  async execute({ query }, ctx) {
+    return ctx.host.mcp.callTool("linear", "list_issues", { query });
+  },
+});
+```
+
+`host.mcp.names()` lists connection names.
+`listTools(name)` / `callTool(name, tool, args)` call into a named
+connection.
+
+## Related
 
 - [Host MCP OAuth](/docs/guides/mcp-oauth.md): `mcp oauth`, Connect, `--store`
 - [Tools](/docs/reference/tools.md): authored tools that wrap MCP connections
 - [Webhooks](/docs/guides/webhooks.md): calling MCP connections from handlers
+- [Peer agents](/docs/guides/agent-to-agent.md): when a specialist is its
+  own agent
 
 ---
 
 Source: /docs/reference/evals.md
 
-# Evals reference
+# Evals
 
-This page is the complete authoring and runner contract for
-`@cursor/july/evals`. Start with the [Evals guide](/docs/evals.md) for the
-workflow and first regression case.
+Evals run fixed cases against an agent and record whether its turns,
+tools, events, and output meet a contract. Files under the project-root
+`evals/` directory define cases with `@cursor/july/evals`; the runner
+discovers their IDs, executes them, and reports every assertion. See the
+[Evals guide](/docs/evals.md) for the regression workflow.
 
-## Discovery and case IDs
+## Eval discovery and case IDs
 
 Eval files live under the project-root `evals/` directory and end in
 `.eval.ts` or `.eval.js`. The path under that directory becomes the
@@ -5631,15 +5917,15 @@ Those cases are `prs/checkout` and `prs/search` when the file is
 `evals/prs.eval.ts`. Case IDs must be unique single path segments.
 
 A file can also export an array of `defineEval` calls. The runner names
-them with zero-padded indexes such as `sql/0000`. Use named `cases` for
-handwritten scenarios and arrays for loaded datasets.
+them with zero-padded indexes such as `sql/0000`. Named `cases` give
+handwritten scenarios stable IDs; arrays fit loaded datasets.
 
 `iterations` repeats one datapoint from 1 to 100 times. For
 `iterations: 3`, `weather/nyc` expands to `weather/nyc/1`,
 `weather/nyc/2`, and `weather/nyc/3`; selecting `weather/nyc` runs all
 three.
 
-## Configuration
+## Eval configuration
 
 Every running suite needs `evals/evals.config.ts` with
 `maxConcurrency`:
@@ -5660,38 +5946,39 @@ export default defineEvalConfig({
 | `timeoutMs` | Per-case timeout; case/file, CLI, then config precedence |
 | `judge` | Default model for `t.judge` |
 | `reporters` | Objects notified as cases and runs complete |
-| `maxPlaygroundRuns` | Number of server-side batches kept in playground history |
+| `maxPlaygroundRuns` | Number of server-side batches kept in playground history; defaults to 20 |
 
 A case can override `description`, `tags`, `timeoutMs`, `iterations`,
 `judge`, `reporters`, and `metadata`. Case metadata merges over
 file-level metadata; case reporters add to the file's reporters.
 
-## Drive turns with `t.send`
+## Send turns in a case
 
 `await t.send(message, options?)` runs one turn and waits until it
 finishes, fails, or parks for approval. Several sends in one test share
 the session.
 
 The returned turn exposes its assistant `message`, `sessionId`,
-`events`, ordered `toolCalls`, `ok`, and turn `index`. Assertions on the
-turn inspect only that turn; assertions on `t` inspect the whole run.
-Useful run values include `t.reply`, `t.events`, `t.turns`,
-`t.sessionId`, and the timeout `t.signal`.
+`events`, ordered `toolCalls`, `ok`, and one-based `index`. Assertions
+on the turn inspect only that turn; assertions on `t` inspect the whole
+case. Run values include `t.reply`, `t.events`, `t.turns`,
+`t.sessionId`, `t.iteration`, `t.iterations`, and the timeout
+`t.signal`.
 
 These options apply on the first send because they shape the session:
 
 | Option | Contract |
 | --- | --- |
 | `workspaceFiles` | Relative path-to-content map seeded into the session workspace |
-| `workspaceDir` | Absolute local harness working directory |
+| `workspaceDir` | Absolute working directory for a new local session |
 | `cloud` | Cloud session options merged over the agent's static cloud config |
 
-Use `turn.expectOk()` when later test steps depend on that turn
-succeeding.
+Use `turn.expectOk()` when later test steps depend on the turn
+succeeding. It throws when the turn failed.
 
 ## Trajectory assertions
 
-Assertions record failures and let the test continue, so one case
+Assertions record failures without stopping the test, so one case
 reports every violated contract.
 
 | Assertion | Checks |
@@ -5814,53 +6101,43 @@ export default rows.map(row =>
 );
 ```
 
-Materialize API-backed evidence before running a large suite. Commit
-the exact payload, diff, or metadata revision and seed it with
-`workspaceFiles`.
-
 ## Reporters and results
 
 Built-in reporters include `JUnit({ filePath, suiteName? })` and
 `Artifacts({ dir })`. Custom reporters can expose `onRunStart`,
-`onEvalComplete`, and `onRunComplete`. Reporter errors are logged and
-do not change the eval verdict.
+`onEvalComplete`, and `onRunComplete`.
 
-JSON output contains run totals plus one result per case. A result can
-include the case ID, verdict, assertions, session ID, inputs, tool
-calls, metrics, logs, duration, metadata, tags, final text, and error or
-skip details.
+JSON output contains run totals and one result per case. Results include
+the case ID, verdict, assertions, session ID, inputs, final text, tools,
+tool calls, metrics, logs, duration, metadata, tags, and any error or
+skip reason.
 
-## CLI selection and artifacts
+## Select cases
 
 ```bash
 agent-sdk eval --dir . --list
 agent-sdk eval --dir .
 agent-sdk eval --dir . builds/checkout
 agent-sdk eval --dir . --tag smoke
-agent-sdk eval --dir . --verbose
 ```
 
 ID filters match an exact ID and its descendants. Repeated IDs use OR;
 repeated tags use OR. When both are present, a case must match both
 groups.
 
-The local runner starts an ephemeral server. Default artifacts go under
-`evals/<stamp>/` in the project state directory and include
+## Inspect run artifacts
+
+Default run artifacts go under `evals/<stamp>/` in the project state
+directory and include
 `summary.json`, `results.jsonl`, and `evals/<case-id>.json`.
 `--artifacts <dir>` chooses another destination; `--no-artifacts`
 disables them. This location is independent of `--state-root`.
 
-Model and judge turns resolve credentials in this order:
-`CURSOR_API_KEY`, `CURSOR_API_KEY_FILE`,
-`CURSOR_SERVICE_ACCOUNT_KEY`, then `agent-sdk login`. Listing cases
-needs no credential.
-
-## Playground and hosted runs
+## Run evals against a server
 
-The playground **Evals** view starts batches on its running server and
-keeps their sessions in the normal session list. `--url` targets a
-named running server; `--prod --slug <slug>` targets a hosted
-deployment.
+The playground **Evals** view starts batches on its running server.
+`--url` targets a named running server, and `--prod --slug <slug>`
+targets a hosted deployment.
 
 ```bash
 agent-sdk eval --prod --slug vulnerability-scanner --tag smoke
@@ -5868,17 +6145,16 @@ agent-sdk eval status <eval-id> --prod --slug vulnerability-scanner
 agent-sdk eval cancel <eval-id> --prod --slug vulnerability-scanner
 ```
 
-Server-side batches use the target server's discovered evals and store
-results in its playground history. Local-only reporter and concurrency
-flags do not apply to `--url` or `--prod` runs.
+Server-side batches use the target's discovered cases and return an eval
+ID for `status` or `cancel`. Local reporter and concurrency flags don't
+apply to `--url` or `--prod` runs.
 
 ## Related
 
-- [Evals guide](/docs/evals.md): author and run a regression workflow
-- [CLI reference](/docs/reference/cli.md#eval): every runner flag
-- [Sessions](/docs/reference/sessions.md): event vocabulary used by trajectory checks
-- [Artifacts](/docs/reference/artifacts.md): durable outputs asserted by
-  `taggedArtifact`
+- [Evals guide](/docs/evals.md)
+- [CLI reference](/docs/reference/cli.md#eval)
+- [Sessions](/docs/reference/sessions.md)
+- [Artifacts](/docs/reference/artifacts.md)
 
 ---
 
@@ -5916,10 +6192,10 @@ The extension validates its configuration while the project loads.
 Missing or mistyped settings fail `agent-sdk validate` before a turn
 can call the contributed code.
 
-Extension instructions are appended to the agent's prompt. The root
-agent still needs its own `agent/instructions.md`.
+Extension instructions are appended to the root agent's instructions.
+The root agent still needs its own `agent/instructions.md`.
 
-## See what the extension added
+## Inspect a mount
 
 Run discovery after mounting or upgrading an extension:
 
@@ -6007,18 +6283,14 @@ server. OAuth-backed plugin servers use
 [Host MCP OAuth](/docs/guides/mcp-oauth.md); transport and tool-filter
 details live in [MCP connections](/docs/reference/connections.md).
 
-## What an extension can contain
-
-Share capabilities that can safely join another agent under a
-namespace:
+## Extension contents
 
-- Instructions, tools, skills, MCP and host connections
-- Hooks, channels, schedules, and subagents
-- Artifact kinds and local workspace seed files
+| Ships under the namespace | Ignored |
+| --- | --- |
+| Instructions, tools, skills, MCP and host connections | `agent.ts`, storage, OpenTelemetry |
+| Hooks, channels, schedules, and subagents | Playground code, custom sandbox backends |
+| Artifact kinds and workspace seed files | Nested extensions |
 
-Agent-wide configuration does not compose through a mount.
-`agent.ts`, storage, OpenTelemetry, playground code, custom sandbox
-backends, and nested extensions are ignored in an extension package;
 `agent-sdk validate` reports unsupported paths.
 
 ## Build an extension
@@ -6073,6 +6345,7 @@ namespace-neutral because the consumer chooses the final prefix.
 - [Cloud agents](/docs/guides/cloud-agents.md): delegate repository work
   through an extension
 - [Grok Bot agents](/docs/guides/grokbot-agents.md): consult named bots
+- [Jev](/docs/guides/jev.md): typed answers, then gated writes
 - [Self-improvement](/docs/guides/improve.md): propose source changes
   through pull requests
 - [Project layout](/docs/reference/project-layout.md): contribution slots
@@ -6084,18 +6357,16 @@ Source: /docs/reference/hooks.md
 
 # 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.
+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.
 
-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).
+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
@@ -6144,95 +6415,54 @@ later sessions to read. Delete the file to opt out.
 ## Events and payloads
 
 Keys are event types from the
-[event vocabulary](/docs/reference/sessions.md#which-events-can-i-stream), or `"*"`
+[event vocabulary](/docs/reference/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](/docs/reference/schedules.md), the same API tools get                                                                                                               |
-| `ctx.artifacts`                                     | Session-bound [artifacts](/docs/reference/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](/docs/templates/pr-autofixer.md)    |
-| Block, approve, or rewrite a tool call                                                | [`needsApproval`](/docs/reference/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](/docs/evals.md)                                                                                             |
-
-## Patterns
-
-Usage metering is the [authoring example](#author-a-hook). Three more:
-
-### Alert on failure
+| 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](/docs/reference/schedules.md#reminders), the same API tools get                                                                                  |
+| `ctx.artifacts`                                     | Session-bound [artifacts](/docs/reference/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 |
 
-`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.
+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
@@ -6245,7 +6475,7 @@ export default defineHook({
       if (
         pagerUrl === undefined ||
         ctx.session.purpose === "eval" ||
-        event.data.message === "turn interrupted"
+        event.data.status === "cancelled"
       ) {
         return;
       }
@@ -6265,78 +6495,47 @@ export default defineHook({
 });
 ```
 
-### Mirror the transcript
-
-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.
-
-```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)
-      );
-    },
-  },
-});
-```
+## Hooks vs channels vs evals
 
-### Keep derived state across a replace
+All three consume the same stream, for different jobs:
 
-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](/docs/templates/pr-autofixer.md)    |
+| Block, approve, or rewrite a tool call                                                | [`needsApproval`](/docs/reference/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](/docs/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`](/docs/reference/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`](/docs/reference/cli.md#logs).
 
-Continue with these pages:
+## Related
 
+- [Hooks guide](/docs/guides/hooks.md): meter usage and page on failure
 - [Sessions and streaming](/docs/reference/sessions.md): the event vocabulary hooks observe
 - [OpenTelemetry](/docs/guides/opentelemetry.md): OTLP traces and metrics
   from the same event stream
@@ -6348,34 +6547,33 @@ Continue with these pages:
 
 Source: /docs/reference/http-api.md
 
-# HTTP API reference
+# HTTP API
+
+Agent SDK hosts expose one public HTTP surface. In the default
+multi-agent layout, each agent uses `/<slug>/v1/*`; `--mode single`
+serves the same routes at `/v1/*`. Routes use the agent's HTTP auth
+chain, and session-owned resources return `403` to another principal.
 
-Agent SDK hosts expose the same public HTTP surface. In the default
-multi-agent layout each agent is namespaced under its slug
-(`/<slug>/v1/session`, `/<slug>/playground`), with host-level routes at
-the root. With `--mode single`, one agent serves the same surface
-unslugged (`/v1/*`).
+Unless a section says otherwise, the default auth policy is
+`localDevStrict()`. `--bearer-token` replaces it with bearer auth, and
+`--allow-anonymous` replaces it with anonymous access. Built-in JSON
+routes use `{ ok: false, error: "<code>", message? }` for errors; MCP
+uses JSON-RPC, and custom channel handlers define their own responses.
 
-Unless noted otherwise, routes run the agent's HTTP auth chain: the
-default is `localDevStrict()` (loopback only), replaced by `bearerAuth` under
-`--bearer-token` or `allowAll()` under `--allow-anonymous`. Session
-routes also require the caller to be the session's owner (`403`
-otherwise). Errors return JSON
-`{ ok: false, error: "<code>", message? }` with a matching HTTP status.
+## Host routes
 
-## Host-level routes (multi-agent mode)
+These routes live at the host root in multi-agent mode. The index routes
+exist only when the playground is enabled.
 
-These routes live at the host root, above any agent. The two index
-routes exist only while the playground is enabled (`--no-playground`
-removes them) and run no auth. The documentation site is mounted in
-both layouts and removed by `--no-docs`.
+| Route | Contract |
+| --- | --- |
+| `GET /` | HTML index of mounted agents; no auth |
+| `GET /v1/agents` | JSON index of mounted agents; no auth |
+| `GET /docs`, `GET /docs/*` | Documentation site in either layout; no auth |
+| `GET /v1/health` | Host liveness; no auth |
 
-| Route                      | What it does                                                                                                                 |
-| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `GET /`                    | A web index of every mounted agent, linking to playgrounds (playground only)                                                 |
-| `GET /v1/agents`           | The JSON index of mounted agents (playground only, no auth)                                                                  |
-| `GET /docs`, `GET /docs/*` | This documentation, served as a static site (both layouts, no auth)                                                          |
-| `GET /v1/health`           | Host-level liveness, no auth                                                                                                 |
+`--no-playground` removes the two index routes. `--no-docs` removes the
+documentation site.
 
 ## Start a session
 
@@ -6389,18 +6587,18 @@ curl -X POST http://127.0.0.1:3000/<slug>/v1/session \
 #  "playgroundUrl":"…?sessionId=ses_…","traceUrl":"…/v1/session/ses_…/events"}
 ```
 
-The response returns as soon as the message is accepted; follow the
-stream for progress. The continuation token is the follow-up credential,
-and `playgroundUrl` deep-links the session in the playground.
+Once accepted, the response returns `sessionId` for inspection and
+`continuationToken` for follow-ups; follow the stream for progress.
 
-| Body field | Meaning |
+| Body field | Contract |
 | --- | --- |
 | `message` | Required user message |
-| `title` | Session title |
+| `title` | Display title |
 | `dryRun` | Run read tools and stub write tools |
-| `asOf` | ISO-8601 instant with a timezone, frozen at create; the prompt states it, `ctx.now()` returns it, and tool calls with relative, later-than-`asOf`, or omitted schema-declared time bounds are refused. `400` when unusable |
-| `workspaceFiles` | UTF-8 files written into the session workspace |
+| `asOf` | ISO-8601 instant with a timezone; sets `ctx.now()` and rejects omitted, relative, or later declared tool time arguments. Invalid values return `400` |
+| `workspaceFiles` | Relative files added to the session workspace |
 | `cloud` | Per-session cloud options merged over the agent defaults |
+| `purpose` | Use `"eval"` to mark regression traffic |
 
 ## Send a follow-up
 
@@ -6412,15 +6610,15 @@ curl -X POST http://127.0.0.1:3000/<slug>/v1/session/ses_… \
   -d '{"continuationToken":"http:…","message":"Make it shorter."}'
 ```
 
-Works for any chat session, including ones created by custom channels.
-Each accepted follow-up rotates the token, and the response carries the
-new one. Sending to a busy session interrupts the in-flight turn, waits
-for it to settle, then sends.
+The route accepts any chat session, including one created by a custom
+channel. Each accepted follow-up rotates the continuation token and
+returns the replacement. A message sent to a busy session interrupts
+the active turn before starting.
 
-Expect `409` on a stale token or a task session. Task sessions do not accept
-follow-ups. Expect `403` when the caller is not the session owner.
+The route returns `409` for a stale token or task session, and `403`
+when the caller doesn't own the session.
 
-## Stream a session
+## Stream or replay session events
 
 `GET /v1/session/:sessionId/stream` is the live NDJSON feed.
 
@@ -6428,44 +6626,36 @@ follow-ups. Expect `403` when the caller is not the session owner.
 curl -N 'http://127.0.0.1:3000/<slug>/v1/session/ses_…/stream?startIndex=0'
 ```
 
-One NDJSON event per line, from `startIndex`, then following live. The
-default is `0`: omitting the parameter replays the entire recorded
-stream before following. Pass the last index you've seen plus one to
-resume without duplicates. The stream is durable and reconnectable. For
-the vocabulary, see
-[Sessions](/docs/reference/sessions.md#which-events-can-i-stream).
+The route replays one event per line from `startIndex`, then follows new
+events. The default `0` replays the full stream. To reconnect without
+duplicates, pass the last index you received plus one.
 
 `GET /v1/session/:sessionId/events` returns a one-shot NDJSON dump.
-Pass `?format=json` for `{ sessionId, events, playgroundUrl }`.
+Pass `?format=json` for `{ sessionId, events, playgroundUrl }`. See
+[Stream events](/docs/reference/sessions.md#stream-events) for the event vocabulary.
 
-## Stop and list
+## Manage sessions
 
-`POST /v1/session/:sessionId/stop` interrupts the in-flight turn without
-sending a new message. `GET /v1/sessions` lists sessions owned by the
-calling principal. Under `serve --dev` on loopback it includes all
-sessions, which is how webhook and schedule sessions show up in the
-playground.
-
-## Session cost
-
-`GET /v1/session/:sessionId/cost` returns the session's cost report:
-per-turn token usage and the engine's estimated cost, folded from
-`turn.completed` events. It runs the same owner check as the other
-session routes and returns `404` for an unknown session. The
-[`agent-sdk cost`](/docs/reference/cli.md#cost) command reports the same data.
+| Route | Contract |
+| --- | --- |
+| `POST /v1/session/:sessionId/stop` | Interrupt the active turn without sending another message |
+| `GET /v1/sessions` | List sessions owned by the caller |
+| `GET /v1/session/:sessionId/cost` | Return per-turn token usage and estimated cost |
 
-## Approvals
+On loopback under `serve --dev`, the session list includes every
+principal so webhook and schedule sessions appear in the playground.
+The cost route returns `404` for an unknown session.
 
-Two routes list and resolve parked tool calls.
+## Resolve tool approvals
 
-| Route                                           | What it does                                                   |
-| ----------------------------------------------- | -------------------------------------------------------------- |
-| `GET /v1/session/:sessionId/approvals`          | Pending human-in-the-loop tool approvals                       |
-| `POST /v1/session/:sessionId/approvals/:callId` | Resolve one: `{"decision":"approve"}` or `{"decision":"deny"}` |
+| Route | Contract |
+| --- | --- |
+| `GET /v1/session/:sessionId/approvals` | List pending tool approvals |
+| `POST /v1/session/:sessionId/approvals/:callId` | Resolve one with `{"decision":"approve"}` or `{"decision":"deny"}` |
 
 For the lifecycle, see [Gate a tool on human approval](/docs/reference/tools.md#gate-a-tool-on-human-approval).
 
-## Call a tool directly
+## Call a tool without a model turn
 
 `POST /v1/tools/:toolName` runs a server tool with no model turn.
 
@@ -6477,133 +6667,118 @@ curl -X POST http://127.0.0.1:3000/<slug>/v1/tools/inspect_pr \
 #  "isError":false,"result":{…},"durationMs":12}
 ```
 
-It runs an authored server tool in-process: schema-validated, no model
-turn. An optional `"sessionId"` in the body runs it inside an existing
-session and records it on that session's stream (`409 session_busy`
-for a write-effect call while a turn runs; reads run alongside the
-turn). Agent-execution tools are rejected with `400`, and
-unknown tools with `404` and the list of available names. For the
-semantics, see [Tools](/docs/reference/tools.md#call-a-tool-without-a-model-turn).
+| Body field | Contract |
+| --- | --- |
+| `input` | Tool input; defaults to `{}` |
+| `sessionId` | Bind the call to an existing session |
+| `continuationToken` | Bind the call by its wire continuation token; mutually exclusive with `sessionId` |
 
-An optional `"continuationToken"` (`<channelId>:<key>`, as
-`/v1/sessions` lists it; mutually exclusive with `sessionId`) addresses
-the session by continuation token instead; malformed tokens are
-rejected with `400 invalid_continuation_token`. For the semantics, see
-[Tools](/docs/reference/tools.md#call-a-tool-without-a-model-turn).
+Omit both identifiers for an unbound call. Agent-execution tools return
+`400`, and an unknown name returns `404` with the available names. See
+[Tools](/docs/reference/tools.md#call-a-tool-without-a-model-turn) for session
+binding, busy-session rules, and error codes.
 
-## Discovery
+## Discovery routes
 
 These read-only routes describe the running agent.
 
-| Route                  | What it does                                                                                                                                                                             |
-| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `GET /v1/info`         | The discovered surface: model, tools, skills, MCP connections, subagents, channels and routes (with schemas), schedules, hooks, diagnostics |
-| `GET /v1/tools`        | The live tool catalog: authored server tools plus advertised MCP passthroughs under model-facing names, as light `{ name, title?, source? }` entries. `session` / `continuationToken` query parameters bind the listing to a session identity (advertised inventories can be tenant-scoped); a connection whose listing fails is skipped and reported in `connectionErrors` |
-| `GET /v1/tools/:name`  | One catalog tool's full description: description, execution, `needsApproval`, `effect`, input and output schemas, source connection. Same session binding as the listing; unknown names get `404` with the available names |
-| `GET /v1/health`       | Per-agent liveness, no auth                                                                                                                                                              |
-| `GET /v1/logs?after=N` | Recent server log lines, with a polling cursor                                                                                                                                           |
+| Route | Contract |
+| --- | --- |
+| `GET /v1/info` | Return the discovered model, tools, skills, connections, subagents, channels, schedules, hooks, and diagnostics |
+| `GET /v1/tools` | Return live server tools and advertised MCP tools as `{ name, title?, source? }`; bind tenant-scoped listings with `session` or `continuationToken` |
+| `GET /v1/tools/:name` | Return one tool's description, execution mode, approval and effect rules, schemas, and source |
+| `GET /v1/health` | Return per-agent liveness; no auth |
+| `GET /v1/logs?after=N` | Return recent server logs and the next polling cursor |
 
-## Artifacts
+An unknown tool name returns `404` with available names. If an MCP
+connection can't list its tools, the catalog skips that connection and
+includes it in `connectionErrors`.
 
-Two routes read durable artifacts tagged by `ctx.artifacts` or
-`tag_artifact`. See [Artifacts](/docs/reference/artifacts.md).
+## List and download artifacts
 
-| Route                            | What it does                                                                                          |
-| -------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `GET /v1/artifacts`              | List artifacts as `{ artifacts }`, newest-updated first. Filter with `?kind=`, `?sessionId=`, and `?limit=` (a positive integer) |
-| `GET /v1/artifacts/:id/content`  | Download one artifact's file or blob payload. Served as an attachment, never rendered inline; `404` when the artifact is unknown or carries no content |
+| Route | Contract |
+| --- | --- |
+| `GET /v1/artifacts` | Return `{ artifacts }`, newest-updated first; filter with `kind`, `sessionId`, and a positive `limit` |
+| `GET /v1/artifacts/:id/content` | Download an artifact's file or blob as an attachment; return `404` when no content exists |
 
-Session ownership applies the same way as `GET /v1/sessions`: under
-`serve --dev` on loopback (or `--allow-anonymous`) the list spans all
-principals, while bearer or custom channel auth keeps strict
-per-principal isolation.
+The list follows the same ownership rules as `GET /v1/sessions`. See
+[Artifacts](/docs/reference/artifacts.md) for tagging and record fields.
 
-## Custom channel routes
+## Call custom channel routes
 
-Authored routes mount under `/v1/channels/<id>` with the methods, paths,
-and Zod schemas the channel declared (a
-`POST /<slug>/v1/channels/drive` route, say). Bodies are validated before
-handlers run (`400` on schema violations), and each channel's auth chain
-applies. The GitHub channel verifies `X-Hub-Signature-256` when a
-secret is configured. See [Channels](/docs/reference/channels.md).
+Authored routes mount under `/v1/channels/<id>` with their declared
+methods and paths. The host validates their Zod body and query schemas
+before calling the handler, returning `400` on failure. Each channel's
+auth chain applies. See [Channels](/docs/reference/channels.md).
 
 ## MCP endpoint
 
-`/v1/mcp` serves the Model Context Protocol over streamable HTTP
-(stateless; POST carries the protocol, and GET/DELETE return
-spec-compliant 405s). The tools are `ask` (delegate a message, bounded
-waits), `check` (poll a running session), and `call_tool` (deterministic
-server-tool passthrough, present when the agent has server tools). The
-route runs the same auth chain as the session API. Peer wiring:
-[MCP connections](/docs/reference/connections.md#peer-mcp-connection).
+Both MCP routes use stateless streamable HTTP. Send protocol requests
+with `POST`; `GET` and `DELETE` return `405`.
+
+| Route | Tools and auth |
+| --- | --- |
+| `/v1/mcp` | `ask`, `check`, and `call_tool` when server tools exist; uses the session API auth chain |
+| `/v1/mcp/tools` | Deterministic server tools only; uses the CLI-level loopback, bearer, or anonymous auth chain |
 
-`/v1/mcp/tools` is a second stateless MCP endpoint exposing only the
-agent's deterministic server tools. Hosted cloud turns call back into
-it through the URL configured by `serve --cloud-tools-url`. Unlike
-`/v1/mcp`, it runs the CLI-level auth chain (loopback, bearer, or
-anonymous), not any authored channel auth.
+See [MCP connections](/docs/reference/connections.md#peer-mcp-connection) to connect
+one agent to another.
 
 ## Playground eval routes
 
-The playground Evals tab and `agent-sdk eval --prod` / `--url` use these:
+The playground Evals tab and remote eval commands use these routes:
 
-| Route                           | What it does                                                                                               |
-| ------------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `GET /v1/dev/evals`             | List discovered eval datapoints and project config                                                         |
-| `GET /v1/dev/evals/runs`        | List recent run snapshots, newest first                                                                    |
-| `POST /v1/dev/evals/runs`       | Start an eval run (`{filterIds?, tags?}`); `202` with a snapshot (`runId` is the Eval ID), `404` when nothing matches, `409` when one is running |
-| `GET /v1/dev/evals/runs/:runId` | Poll a run's progress                                                                                      |
-| `POST /v1/dev/evals/runs/:runId/cancel` | Cancel a running batch; `200` with snapshot, `404` unknown, `409` when not running |
+| Route | Contract |
+| --- | --- |
+| `GET /v1/dev/evals` | List discovered cases and eval config |
+| `GET /v1/dev/evals/runs` | List recent run snapshots, newest first |
+| `POST /v1/dev/evals/runs` | Start `{ filterIds?, tags?, timeoutMs?, verbose? }`; return `202`, `404` for no match, or `409` while another run is active |
+| `GET /v1/dev/evals/runs/:runId` | Return progress and the final snapshot |
+| `POST /v1/dev/evals/runs/:runId/cancel` | Cancel an active run; return `404` when unknown or `409` when no longer running |
 
-Eval runs are asynchronous. Poll the run route for case progress and
-the final `completed` or `failed` status. Batch errors appear on the
-snapshot returned by the poll. Entries within `filterIds` and `tags`
-use OR semantics. When both fields are present, a case must match one
-entry from each field. Listed runs persist across restarts when
-durable storage is configured. Otherwise they are
-process-memory only.
+Poll the run route until its status is `completed`, `failed`, or
+`cancelled`. Entries within `filterIds` and `tags` use OR semantics;
+when both fields are present, a case must match each group.
 
 ## Dev-mode routes
 
 These routes exist only under `serve --dev`.
 
-| Route                                | What it does                                                                                               |
-| ------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
+| Route | Contract |
+| --- | --- |
 | `POST /v1/dev/schedules/:scheduleId` | Dispatch a schedule by hand, exactly once. Returns `{scheduleId, sessionIds}` |
-| `GET /v1/dev/reminders`              | List reminders                                                                                             |
-| `POST /v1/dev/reminders/:reminderId` | Fire a reminder by hand                                                                                    |
+| `GET /v1/dev/reminders` | List reminders |
+| `POST /v1/dev/reminders/:reminderId` | Fire a reminder by hand |
 
 Schedules and reminders never fire automatically in dev mode. These
-routes are the only way they run, which keeps iteration deterministic.
+routes run them manually.
 
 ## Playground assets
 
 `GET /playground` and `GET /playground/assets/:file` serve the
-playground (omitted with `--no-playground`). It calls the JSON API
-above and has no privileged surface.
+playground. `--no-playground` removes both routes.
 
 ## Status codes
 
-Error responses use a small, consistent set of status codes.
+Built-in routes use these common status codes.
 
-| Code  | Meaning here                                                                                                               |
-| ----- | -------------------------------------------------------------------------------------------------------------------------- |
-| `400` | Schema-invalid body or query, agent-execution tool called on the host, malformed request                                   |
-| `401` | No auth policy admitted the request                                                                                        |
-| `403` | Authenticated, but not the session owner                                                                                   |
-| `404` | Unknown session, tool, schedule, reminder, or eval run; no eval datapoints match a run request                              |
-| `405` | Wrong method (GET on the MCP endpoint, say)                                                                                |
-| `409` | Stale continuation token, a busy session-bound tool call, a non-followable task session, or an eval run already in progress |
-| `202` | Accepted for background work (GitHub `{ task }` hooks, eval runs)                                                          |
-
-## What's next
+| Code | Meaning |
+| --- | --- |
+| `400` | Invalid body, query, tool input, or request shape |
+| `401` | No auth policy admitted the request |
+| `403` | The caller is authenticated but doesn't own the resource |
+| `404` | A named resource doesn't exist, or an eval selection matches no cases |
+| `405` | The route doesn't accept this method |
+| `409` | The resource state rejects the request, such as a stale token or busy write |
+| `202` | The request was accepted for asynchronous work |
+| `500` | A write-effect tool can't create its session workspace (`workspace_unavailable`) |
 
-Continue with these pages:
+## Related
 
-- [Sessions and streaming](/docs/reference/sessions.md): the handles and events these
-  routes traffic in
-- [Channels](/docs/reference/channels.md): authoring your own routes
-- [Deployment](/docs/deployment.md): auth on real hosts
+- [Sessions](/docs/reference/sessions.md)
+- [Channels](/docs/reference/channels.md)
+- [Tools](/docs/reference/tools.md)
+- [Deployment](/docs/deployment.md)
 
 ---
 
@@ -6611,19 +6786,17 @@ Source: /docs/reference/instructions.md
 
 # Instructions
 
-`agent/instructions.md` is the always-on system prompt. It's the one
-piece of prose the model sees on every turn. It's required on the root
-agent; subagents may inline `instructions` in their `agent.ts` instead.
+Agent instructions form the always-on system prompt and reach the model
+on every turn. A root agent requires them; a subagent may inline
+`instructions` in `agent.ts` instead.
 
 ## Authoring forms
 
-Three forms cover every case.
-
-| Form | Reach for it when |
+| Form | Use it when |
 | --- | --- |
-| `agent/instructions.md` | Plain Markdown for most agents. |
-| `agent/instructions.ts` | Generated prompts. Default-export `defineInstructions({ markdown })` or a plain string. |
-| `agent/instructions/` directory | A long prompt split across files, composed in filename order. |
+| `agent/instructions.md` | Plain Markdown for most agents |
+| `agent/instructions.ts` | Generated prompts. Default-export `defineInstructions({ markdown })` or a plain string |
+| `agent/instructions/` directory | A long prompt split across files, composed in filename order |
 
 ```ts
 // agent/instructions.ts
@@ -6634,22 +6807,17 @@ export default defineInstructions({
 });
 ```
 
-## How instructions reach the model
+## Delivery
 
-On the local runtime, instructions land in the session workspace as
-`AGENTS.md`, and the harness loads them natively. On the cloud runtime,
-they're prepended to the first prompt, because the cloud VM doesn't
-share the local session workspace.
+Local and cloud turns receive the composed instructions. They aren't
+written into the session workspace. Parent directories can still
+contribute ambient `AGENTS.md` and `.cursor` settings; [Agent config:
+local cwd](/docs/reference/agent-config.md#local-cwd) covers how to control that.
 
-The local workspace is a real Cursor project directory, so the harness
-may also load ambient `AGENTS.md` and `.cursor` config from ancestor
-directories. [Agent config → Local cwd](/docs/reference/agent-config.md#local-cwd)
-covers controlling that.
+## Contents
 
-## What to put in instructions
-
-Keep them a few lines: identity, when to use which tool, output shape.
-The [quickstart PR approver](/docs/quickstart.md) is the pattern:
+Keep them a few lines: identity, when to use which tool, and the output
+shape. The [quickstart PR approver](/docs/quickstart.md) is the pattern:
 
 ```md
 # PR approver
@@ -6663,21 +6831,13 @@ You review GitHub pull requests. Be specific and brief.
 End with one sentence: the verdict and why.
 ```
 
-- Name the tools and the decision rule ("use X before answering about
-  Y"), not general encouragement.
-- State the output contract: length, format, fences. That contract is
-  what your [evals](/docs/evals.md) gate.
-- Move procedures to [skills](/docs/reference/skills.md). A multi-step workflow the
-  model only sometimes needs belongs in `agent/skills/`, where it loads
-  on demand and keeps the always-on prompt small.
-
-Instructions are the third lever in the
-[hillclimbing loop](/docs/hillclimbing.md), after host preparation and evidence
-shape. If a fixture keeps failing, look there before rewriting prose.
-
-## What's next
+Name the tools and the decision rule ("use X before answering about
+Y"), not general encouragement. State the output contract, including
+length, format, and fences, so your [evals](/docs/evals.md) can gate it.
+Put multi-step workflows the model only sometimes needs in
+`agent/skills/`; they load on demand and keep the always-on prompt small.
 
-Continue with these pages:
+## Related
 
 - [Skills](/docs/reference/skills.md): procedures the model loads only when relevant
 - [Agent config](/docs/reference/agent-config.md): the file next to this one
@@ -6690,55 +6850,38 @@ Source: /docs/reference/playground.md
 
 # Playground
 
-Every served agent ships with a web playground at
+`agent-sdk serve` enables a web playground at
 `http://127.0.0.1:3000/<slug>/playground` (or `/playground` in single
-mode). Anything you can do there you can also do with curl.
-
-## What it does
-
-Use the playground to chat, try channel routes, and inspect sessions.
-
-- **Chat** with the agent. Text and reasoning stream live, and tool
-  calls appear inline with their arguments, output, and error state.
-- **Slash commands**: custom channel routes become composer commands
-  (a `drive` route becomes `/drive <pr-url>`), with `/help` and
-  autocomplete.
-- **Try** any channel route from the Agent surface. The modal remembers
-  your last body per endpoint and has Copy curl, and a successful Try
-  opens the created session.
-- **Sessions**: browse the sessions you own (chat, custom-channel,
-  schedule tasks) and replay their event streams. In `--dev` on
-  loopback, or with `--allow-anonymous`, the list includes every
-  principal. Search by session ID to filter the list, or press Enter
-  to open an ID directly. "Open trace" renders a saved event stream.
-- **Approvals**: parked `needsApproval` tool calls render Approve /
-  Deny buttons.
-- **Evals**: list and run filesystem evals from the browser (backed by
-  `/v1/dev/evals`). Schedule hand-dispatch still requires `--dev`.
-- **The surface**: inspect the discovered tools, skills, subagents, MCP
-  connections, channels, and hooks.
-- **Custom tool chips**: drop `agent/playground/tools/<toolName>.tsx` to
-  change how that tool renders. Chips compile from the agent tree;
-  an [extension](/docs/reference/extensions.md) cannot contribute them.
-- **Raw events pane**: flip it on to inspect the event stream.
-- **Logs tab**: recent server log lines, polled from `GET /v1/logs`.
-
-In multi-agent mode each agent has its own playground at
-`/<slug>/playground`, and `/` is an index of them all.
-
-## Share it beyond localhost
+mode). In multi-agent mode, each agent has its own playground, and `/`
+lists them all.
+
+## Playground surfaces
+
+| Surface | What you can do |
+| --- | --- |
+| Chat | Talk to the agent. Text and reasoning stream live, and tool calls appear inline with their arguments, output, and error state |
+| Slash commands | Custom channel routes without path parameters become composer commands; GitHub and Slack ingress routes are excluded. A `drive` route becomes `/drive <pr-url>`, with `/help` and autocomplete |
+| Try | Invoke a custom channel route from the Agent tab. The modal remembers your last body per endpoint, copies curl, and opens a session when the route creates one |
+| Runs | Browse the sessions you own and eval runs. Search by title or identifier; open sessions in Chat, Trace, or Raw and eval runs in Evals |
+| Approvals | Parked `needsApproval` tool calls render Approve / Deny buttons |
+| Evals | List and run filesystem evals from the browser |
+| Agent | Inspect the discovered tools, skills, subagents, MCP connections, channels, and hooks |
+| Raw | Inspect the selected session's event stream |
+| Logs | Recent server log lines, polled from `GET /v1/logs` |
+
+In `--dev` on loopback, or with `--allow-anonymous`, the session list
+includes every principal.
+
+## Remote access
 
 The default `localDevStrict()` auth admits direct loopback calls only
 and rejects proxy-forwarding headers, so a tunnel or LAN address won't
-work
-until you pass `--bearer-token <secret>` (or
+work until you pass `--bearer-token <secret>` (or
 `serve(dir, { authToken })`). Open the playground on the remote device
-and paste the token into the token field in the navbar. `--allow-anonymous` is the
-demo-only alternative for trusted networks.
-
-## What's next
+and paste the token into the token field in the navbar.
+`--allow-anonymous` is the demo-only alternative for trusted networks.
 
-Continue with these pages:
+## Related
 
 - [HTTP API](/docs/reference/http-api.md): the HTTP surface the playground uses
 - [Sessions and streaming](/docs/reference/sessions.md): the streams it renders
@@ -6775,7 +6918,7 @@ to the directory name. When serving multiple agents, the slug is the
 directory name and must match `[A-Za-z0-9][A-Za-z0-9_-]*` (and not the
 reserved `v1`, `playground`, or `docs` segments).
 
-## Project overview
+## Project tree
 
 Most projects start with this shape.
 
@@ -6800,8 +6943,8 @@ my-agent/
 ```
 
 Evals live in `evals/` at the project root, a sibling of `agent/`, never
-inside it. `agent/evals/` is silently ignored. See
-[Evals](/docs/evals.md).
+inside it. `agent/evals/` is ignored, and `validate` warns about it.
+See [Evals](/docs/evals.md).
 
 ## Folder reference
 
@@ -6819,30 +6962,26 @@ Each path maps to a capability and a reference page.
 | `agent/extensions/<ns>.ts` or `agent/extensions/<ns>/` | A mounted extension or Cursor plugin; its contributions become `<ns>__<name>` | [Extensions](/docs/reference/extensions.md) |
 | `agent/channels/*.ts` | HTTP surfaces beyond the built-in session API; `slack.ts` and `github.ts` use the platform packs | [Channels](/docs/reference/channels.md) |
 | `agent/hooks/*.ts` | Observe-only event subscribers, never fatal | [Hooks](/docs/reference/hooks.md) |
-| `agent/otel.ts` | Factory-only OTLP authoring (`defineOtel`). Public path is env / `serve({ otel })`. | [OpenTelemetry](/docs/guides/opentelemetry.md) |
-| `agent/storage.ts` | `defineStorage` backend for the durable `host.kv` / `host.files` APIs | None |
 | `agent/artifacts.ts` | `defineArtifacts` kinds, the `tag_artifact` opt-in, and retention | [Artifacts](/docs/reference/artifacts.md) |
 | `agent/result.ts` | `defineResult` host `commit` on the final assistant text (`throw` or `ctx.reject`) | None |
 | `agent/schedules/*` | Cron-driven runs (UTC, 5-field; never auto-fire under `--dev`) | [Schedules](/docs/reference/schedules.md) |
-| `agent/sandbox/workspace/**` | Seed files copied into each local session workspace | [Sessions](/docs/reference/sessions.md#what-goes-into-a-local-session-workspace) |
-| `agent/playground/` | Custom playground tool chips | [Playground](/docs/reference/playground.md) |
+| `agent/reminders/*.ts` | Named reminder handlers that stay armed across restarts | [Schedules](/docs/reference/schedules.md#reminders) |
+| `agent/sandbox/workspace/**` | Seed files copied into each local session workspace | [Sessions](/docs/reference/sessions.md#local-session-workspace) |
 | `agent/lib/` | Import-only shared code, never discovered | None |
 | `evals/evals.config.ts` | Shared eval settings (e.g. `maxConcurrency`); required when evals exist | [Evals](/docs/evals.md) |
 | `evals/**/*.eval.ts` | Filesystem evals; case id = path under `evals/` | [Evals](/docs/evals.md) |
 
-`agent/lib/` is the only place for shared code. Everything else under
-`agent/` is discovery surface. A stray `.ts` file in one of these
-folders is treated as a definition.
+Use `agent/lib/` for shared imports. A `.ts` file in one of the listed
+discovery folders loads as a definition; unrecognized directories
+produce a validation warning.
 
-## Why didn't the Agent SDK discover my file?
+## Inspect discovery
 
 Run `agent-sdk validate --dir .` and `agent-sdk info --dir .`.
 `validate` prints diagnostics, and `serve` refuses to start on
 error-severity ones. Warnings, such as cloud runtime combined with
 local-only capabilities, print but don't block. `info` lists the discovered
-surface, so a missing tool or channel shows up immediately. From
-there, check the folder reference: the file is usually in the wrong directory
-or has the wrong extension.
+surface, so a missing tool or channel shows up immediately.
 
 ```bash
 agent-sdk validate --dir .    # diagnostics; non-zero exit on errors
@@ -6850,51 +6989,50 @@ agent-sdk info --dir .        # human-readable surface
 agent-sdk info --dir . --json # machine-readable project info (same shape as GET /v1/info)
 ```
 
-## What's next
-
-Continue with these pages:
+## Related
 
 - [Agent config](/docs/reference/agent-config.md): the runtime config at the root
 - [Tools](/docs/reference/tools.md): add typed actions under `agent/tools/`
+- [CLI](/docs/reference/cli.md): commands that discover this tree
 
 ---
 
 Source: /docs/reference/prompt.md
 
-# `prompt`
+# Prompt strings
 
-Authoring helper for long strings that live next to indented TypeScript:
-tool descriptions, reminder `prompt` fields, GitHub channel `context`,
-and error messages.
+The `prompt` template tag keeps multi-line strings aligned with the
+surrounding TypeScript while returning dedented text. Use it for tool
+descriptions, reminder prompts, channel context, and errors. Import it
+from the package root or the dedicated entrypoint:
 
 ```ts
 import { prompt } from "@cursor/july";
 // or: import { prompt } from "@cursor/july/prompt";
 ```
 
-## `prompt\`…\``
+## Dedented strings
 
-Returns a single dedented string. Common leading whitespace is stripped;
-a leading newline after the opening backtick is dropped so the usual
-multiline form stays readable in source.
+`prompt` returns one string. It removes the common leading whitespace
+and one newline immediately after the opening backtick.
 
 ```ts
 throw new Error(prompt`
-  It is outside business hours (Mon–Fri 9am–5pm ET).
+  It is outside business hours (Mon-Fri 9am-5pm ET).
   Use request_author_approval, or pass approval=human_request.
 `);
 ```
 
 Blank lines inside the body are preserved. Relative indentation after the
-common prefix is kept (handy for nested bullet lists).
+common prefix is preserved, so nested lists keep their shape.
 
 When interpolating multi-line values (for example a list of services), give
 those lines the same indent as the `prompt` body so dedent stays consistent.
 
-## `prompt.lines\`…\``
+## Line arrays
 
-Same dedent rules, but returns `string[]`, one entry per line. Use this
-where an API wants separate lines (for example GitHub channel `context`):
+`prompt.lines` applies the same rules and returns `string[]`, with one
+entry per line. Use it when an API accepts separate context lines:
 
 ```ts
 context: prompt.lines`
@@ -6904,13 +7042,18 @@ context: prompt.lines`
 `
 ```
 
+## Related
+
+- [Tools](/docs/reference/tools.md)
+- [Channels](/docs/reference/channels.md)
+
 ---
 
 Source: /docs/reference/schedules.md
 
 # Schedules and reminders
 
-Two ways an agent acts without an inbound message. A schedule is
+An agent can act without an inbound message in two ways. A schedule is
 deploy-time cron: "every weekday at 09:00, summarize open incidents." A
 reminder is a runtime wake bound to one conversation: "re-check this
 PR's CI in two hours." Schedules live in the filesystem; reminders are
@@ -6921,10 +7064,9 @@ created by running code.
 Cron expressions are standard 5-field, evaluated in UTC with minute
 granularity.
 
-### Schedules in Markdown
+### Markdown schedules
 
-A plain markdown file with `cron:` frontmatter is a fire-and-forget
-task:
+A markdown file with `cron:` frontmatter is a fire-and-forget task:
 
 ```md
 ---
@@ -6938,10 +7080,10 @@ Each firing starts a task-mode session: the body is the prompt, the
 session runs to `session.completed` or `session.failed`, and it isn't
 followable.
 
-### Schedules as handlers
+### Schedule handlers
 
-`defineSchedule` with a `run` handler gives you full control, most
-usefully to hand the work into a channel so its delivery events fire:
+Use `defineSchedule` with a `run` handler to call tools or hand work into
+a channel so its delivery events fire:
 
 ```ts
 import { defineSchedule } from "@cursor/july/schedules";
@@ -6950,7 +7092,6 @@ import webhook from "../channels/webhook.js";
 export default defineSchedule({
   cron: "*/30 * * * *",
   async run({ receive, waitUntil, appAuth, host }) {
-    // optional: await host.mcp.callTool("units", "celsius_to_fahrenheit", { value: 0 });
     waitUntil(
       receive(webhook, {
         message:
@@ -6969,14 +7110,12 @@ schedule-scoped principal for work the agent does on its own behalf),
 and `host` (shared services: `host.mcp`, `host.github`, `host.slack`,
 `host.reminders`).
 
-### Dispatch and dev mode
+### Dispatch a schedule
 
-In production (`agent-sdk serve`), schedules fire on their cron
-cadence. Disable them with `--no-schedules`. There's no cross-host
-coordination, so run them in exactly one process per project.
-
-In dev (`serve --dev`), schedules never fire automatically. Dispatch one
-by hand, exactly once, through the same path production uses:
+| Mode | What fires |
+| --- | --- |
+| Production `agent-sdk serve` | Cron cadence. `--no-schedules` disables them. Run them in exactly one process per project |
+| `serve --dev` | Nothing automatic. Dispatch by hand through the same path production uses |
 
 ```bash
 curl -X POST http://127.0.0.1:3000/<slug>/v1/dev/schedules/heartbeat
@@ -6988,104 +7127,67 @@ The playground can dispatch schedules in dev mode too, and
 
 ## Reminders
 
-A reminder is created at runtime and bound to a channel continuation.
-When it fires, it wakes that conversation. Recurring reminders behave
-like `setInterval`, one-shots like `setTimeout`, and both are durable on
-disk.
+A reminder is created at runtime and bound to a channel continuation. A
+prompt reminder wakes that conversation when it fires; a handler reminder
+runs host code, which can call `followup` to wake it. Recurring reminders
+behave like `setInterval`, and one-shots behave like `setTimeout`. Prompt
+and named-handler reminders stay armed across restarts.
 
 ```ts
 await handle.createReminder({
   purpose: "ci_recheck",
   channelId: "drive",
-  continuationToken: "pr:owner/repo#1",
-  delay: "2h", // or a cron / explicit schedule
+  continuationToken: "pr:acme/checkout#42",
+  delay: "2h",
   prompt: "Re-check CI. Only act if still failing.",
   until: "Cancel once CI is green or the PR is merged.",
 });
 ```
 
-Use `run` when host code should decide what happens on each tick:
+When host code must decide what happens on each tick, author a named
+handler and pass its default export with serializable `args`:
 
 ```ts
-await handle.createReminder({
-  purpose: "ci_recheck",
-  channelId: "drive",
-  continuationToken: "pr:owner/repo#1",
-  every: "30m",
-  async run({ fireCount, followup }) {
-    if (fireCount >= 3) {
-      return { action: "stop" };
-    }
+// agent/reminders/ci_recheck.ts
+import { defineReminder } from "@cursor/july/reminders";
 
+export default defineReminder({
+  async run({ args, followup }) {
     await followup({
-      message: "Re-check CI and report only if the status changed.",
+      message: `Re-check CI for ${String(args.prUrl)}. Report only if the status changed.`,
     });
     return { action: "delivered" };
   },
 });
 ```
 
-This reminder wakes the conversation three times, then stops itself.
-
-The same API is `host.reminders` on channel handlers, tools, and
-schedule runs. An agent can even be given a tool that creates its own
-reminders.
-
-For example, create `agent/tools/remind_me.ts`:
-
 ```ts
-import { defineTool } from "@cursor/july/tools";
-import { z } from "zod";
+import ciRecheck from "./agent/reminders/ci_recheck.js";
 
-export default defineTool({
-  description: "Schedule a one-time reminder in this conversation.",
-  inputSchema: z.object({
-    delay: z
-      .string()
-      .describe("When to wake the conversation, such as 20m or 2h"),
-    prompt: z
-      .string()
-      .min(1)
-      .describe("What the agent should do when it wakes"),
-  }),
-  async execute({ delay, prompt }, ctx) {
-    const reminders = ctx.host.reminders;
-    if (reminders === undefined) {
-      throw new Error("Reminders are disabled on this host.");
-    }
-
-    const continuationToken = ctx.session.continuationKey;
-    if (continuationToken == null) {
-      throw new Error("This session cannot receive reminder follow-ups.");
-    }
-
-    const reminder = await reminders.create({
-      purpose: "user_follow_up",
-      channelId: ctx.session.channelId,
-      continuationToken,
-      delay,
-      prompt,
-    });
-
-    return {
-      reminderId: reminder.id,
-      nextFireAt: reminder.nextFireAt,
-    };
-  },
+await handle.createReminder({
+  purpose: "ci_recheck",
+  channelId: "drive",
+  continuationToken: "pr:acme/checkout#42",
+  every: "30m",
+  handler: ciRecheck,
+  args: { prUrl: "https://github.com/acme/checkout/pull/42" },
 });
 ```
 
-The tool binds the reminder to the current channel conversation. When
-the delay expires, the prompt returns to the same session as a follow-up.
+Use an anonymous `run` handler only for legacy projects that can re-arm
+it after a restart. New projects should use a named handler.
 
-Reminders fire in one of two styles. The **prompt form** (above) sends
-`prompt` into the session, with `until` stating the standing
-cancellation condition for the model to honor. The **run form** passes a
-`run` handler instead: it returns `stop`, `skip`, or `delivered` per
-tick. That's silent host-side policy with no model turn. Run handlers are
-in-memory, so after a restart those reminders are disarmed
-(`handler_lost_on_restart`); re-arm them from the code path that created
-them, or prefer the prompt form.
+| Form | What it does | After a restart |
+| --- | --- | --- |
+| Prompt | Sends `prompt` into the session. `until` is the standing cancellation condition for the model | Stays armed |
+| Named handler | Runs a discovered handler with serializable `args`; it starts a model turn only if the handler calls `followup` | Stays armed |
+| Anonymous `run` | Host handler returns `stop`, `skip`, or `delivered` per tick; it starts a model turn only if it calls `followup` | Must be re-armed |
+
+The same API is `host.reminders` on channel handlers, tools, and
+schedule runs. `builtinTools: { reminders: true }` adds
+`reminders_create`, `reminders_list`, and `reminders_cancel` on the
+current conversation; see
+[Agent config: built-in tools](/docs/reference/agent-config.md#built-in-tools).
 
 `--dev` does not auto-fire reminders. Dispatch one by hand:
 
@@ -7096,27 +7198,21 @@ curl -X POST http://127.0.0.1:3000/<slug>/v1/dev/reminders/<id>  # fire one
 
 `handle.dispatchReminder(id)` is the programmatic equivalent.
 
-Two habits worth copying: cancel reminders when their subject
-dies (say, cancel PR-scoped reminders on `pull_request.closed`), and keep
-wake prompts generic. A plain "re-check the PR" works better than
-replaying stale payload details, because the agent re-reads the live
-state when it wakes.
-
-## Schedule or reminder?
+Cancel reminders when their subject dies, for example on
+`pull_request.closed`. Keep wake prompts generic so the agent re-reads
+live state instead of replaying a stale payload.
 
-The split comes down to scope and timing.
+## Schedules vs reminders
 
 |          | Schedule                                                   | Reminder                                        |
 | -------- | ---------------------------------------------------------- | ----------------------------------------------- |
 | Defined  | at deploy time, `agent/schedules/*`                        | at runtime, `createReminder` / `host.reminders` |
 | Scope    | global to the agent                                        | one channel continuation (one conversation)     |
 | Session  | starts a new task session (or hands off through `receive`) | wakes an existing conversation                  |
-| Cadence  | cron (UTC)                                                 | delay, cron, or explicit schedule               |
+| Cadence  | cron (UTC)                                                 | `every`, `cron`, `delay`, or `at`                |
 | Dev mode | manual dispatch only                                       | manual dispatch only (timers off)               |
 
-## What's next
-
-Continue with these pages:
+## Related
 
 - [Channels](/docs/reference/channels.md): `receive` and the delivery events
 - [GitHub guide](/docs/guides/github.md): reminders in a real webhook loop
@@ -7130,9 +7226,12 @@ Source: /docs/reference/sessions.md
 # Sessions, events, and streaming
 
 A session keeps one conversation, its workspace, and an append-only
-record of every message and tool call.
+record of every message and tool call. Continue it with a continuation
+token, inspect it with a session ID, and follow progress on the NDJSON
+stream. Chat sessions wait for follow-ups; task sessions run once and
+stop.
 
-## What does a session contain?
+## Session contents
 
 Each session combines:
 
@@ -7140,12 +7239,12 @@ Each session combines:
 - A conversation the caller can continue
 - A workspace for local turns
 - An NDJSON event stream
-- Runtime state needed to resume after a server restart
+- State that lets the conversation resume after a restart
 
 Sessions belong to the principal that created them. Follow-up, stream,
 and list routes return `403` when another caller tries to access one.
 
-## Which session identifier should I use?
+## Session identifiers
 
 Sessions have two identifiers because conversation routing and
 inspection are different jobs.
@@ -7163,7 +7262,7 @@ accepted follow-up. Reusing a stale HTTP token returns `409`.
 Use the continuation token to keep talking. Use the session ID to
 observe or manage the stored session.
 
-## Which session modes are available?
+## Session modes
 
 | Mode | Created by | What happens after a turn |
 | --- | --- | --- |
@@ -7172,7 +7271,7 @@ observe or manage the stored session.
 
 Task sessions don't accept follow-ups. Trying one returns `409`.
 
-## What happens when I send a follow-up?
+## Follow-ups
 
 A follow-up to an idle chat session starts another turn. Admission when
 the session is already busy depends on the channel:
@@ -7180,23 +7279,21 @@ the session is already busy depends on the channel:
 | Path | Busy-session policy |
 | --- | --- |
 | HTTP playground / `POST /v1/session/:id` / MCP `ask` | **Preempt** (default): interrupt the in-flight turn, wait for it to settle, then run the new message |
-| Slack mentions / DMs / alert-watch | **Coalesce**: leave the active turn running, enqueue the follow-up, and drain queued asks into one follow-up turn when the active turn finishes (no mid-turn tool/hook inject) |
+| Slack mentions / DMs / alert-watch | **Coalesce**: leave the active turn running and queue the follow-up. The running turn may receive it at a tool boundary; any asks that remain become one follow-up turn when it finishes |
 
 Pass `admission: "coalesce"` on `send()` to opt into the Slack policy from
 other callers. Omit it (or pass `"preempt"`) to keep interrupt semantics.
 
 `POST /v1/session/:id/stop` interrupts a turn without sending a new
-message. Interrupted turns record `turn.failed` with
-`"turn interrupted"`. This means the turn was preempted. A whole-message
-Slack `stop` / `@agent stop` does the same for that thread and clears
-pending coalesced nudges.
+message. The stream records `turn.failed` with `status: "cancelled"`;
+the session stays a chat session and can take another follow-up. A
+whole-message Slack `stop` / `@agent stop` does the same for that thread
+and clears pending coalesced follow-ups.
 
-Session-bound deterministic tool calls share the lock only for writes: a
-write-effect call returns `409 session_busy` while a model turn is
-running, a read-effect call runs alongside the turn (see
-[Tools](/docs/reference/tools.md#call-a-tool-without-a-model-turn)).
+See [Tools](/docs/reference/tools.md#call-a-tool-without-a-model-turn) for direct-call
+behavior while a session is busy.
 
-## Which events can I stream?
+## Stream events
 
 Each NDJSON line uses this envelope:
 `{ type, index, sessionId, turnId?, at, data }`. The `index` increases
@@ -7218,13 +7315,11 @@ within one session. The `at` field is an ISO-8601 timestamp.
 
 Pair `actions.requested` with `action.result` to reconstruct the tool
 trajectory. Read `turn.completed.data.usage` for input, output, and
-cache token counts. When `agent/result.ts` is authored, a thrown
-`commit`, a `ctx.reject` that exhausts the two-repair budget, or empty
-assistant text emits `turn.failed` instead of `turn.completed`.
-`ctx.reject(message)` re-runs the same turn with that message so the
-model can revise while tools and the session filesystem are still up.
+cache token counts. With `agent/result.ts`, `turn.failed` is emitted when
+`commit` throws, the turn has no assistant text, or `ctx.reject(message)`
+doesn't lead to an accepted revision.
 
-## How do I stream or replay session events?
+## Stream or replay events
 
 One endpoint handles both live streaming and replay:
 
@@ -7232,27 +7327,27 @@ One endpoint handles both live streaming and replay:
 curl -N 'http://127.0.0.1:3000/<slug>/v1/session/ses_…/stream?startIndex=0'
 ```
 
-Pass `startIndex` to continue after the last event you received. Omit it
-or pass `0` to replay the full session before following new events.
+Pass `startIndex` to continue after the last event you received,
+including after a server restart. Omit it or pass `0` to replay the
+full session before following new events.
 `GET /v1/session/:id/events` returns a one-time dump without staying
 connected.
 
-Event streams replay from disk after a server restart. Conversation
-state resumes from the Cursor SDK store.
-
-## What goes into a local session workspace?
+## Local session workspace
 
 The Agent SDK creates a workspace before the first local turn:
 
 | Source path                        | Lands as                                                                |
 | ---------------------------------- | ----------------------------------------------------------------------- |
-| `instructions.*`                   | `AGENTS.md`                                                             |
 | `skills/*`                         | `.cursor/skills/<name>/SKILL.md`                                        |
 | agent tools (`execution: "agent"`) | scripts in the session workspace, with a catalog in `AGENTS.md` |
 | `sandbox/workspace/**`             | copied in as seed files                                                 |
 | per-send `workspaceFiles`          | written before the turn                                                 |
 
-The local harness uses this workspace as its working directory. Parent
+Instructions reach the model as its system prompt; they aren't written
+into the workspace. See [Instructions](/docs/reference/instructions.md#delivery).
+
+Local turns use this workspace as their working directory. Parent
 directories can contribute `AGENTS.md` and `.cursor` settings. Set
 `local.cwd` when you need a clean parent directory. A channel can also
 provide a different working directory for one session, such as a PR
@@ -7261,20 +7356,16 @@ worktree.
 See [Agent config: local cwd](/docs/reference/agent-config.md#local-cwd) for the
 inheritance rules.
 
-## Where does the Agent SDK store session data?
+## Session storage
 
-Local state lives under `--state-root`. Slugged mounts store it under
-a subdirectory named for the slug.
+Local session state lives under `--state-root`. A slugged mount stores
+it in a subdirectory named for the slug.
 
 Deleting a session directory removes the session from the server: it
 disappears from listings and can no longer be streamed or continued.
 Cloud conversations remain on the Cursor backend.
 
-Nested git checkouts already default `local.cwd` outside the enclosing
-repo. See
-[What goes into a local session workspace?](#what-goes-into-a-local-session-workspace).
-
-## How do I inspect a saved event stream?
+## Inspect a saved event stream
 
 Use `trajectory` with a saved trace:
 
@@ -7283,13 +7374,14 @@ agent-sdk trajectory --events <state-root>/traces/<sessionId>.ndjson
 ```
 
 The command prints tool calls, the reply, and token usage in the same
-JSON shape as `run`. Use **Open trace** in the playground for a visual
-view.
+JSON shape as `run`. Open the session's **Trace** view in the playground
+for a visual timeline.
 
 ## Related
 
 - [HTTP API](/docs/reference/http-api.md)
 - [Hooks](/docs/reference/hooks.md)
+- [Tools](/docs/reference/tools.md)
 
 ---
 
@@ -7305,15 +7397,15 @@ always-on [instructions](/docs/reference/instructions.md).
 
 ## Authoring forms
 
-Three forms cover every case.
+Skills support three authoring forms.
 
 | Form | Reach for it when |
 | --- | --- |
-| `agent/skills/<name>.md` | Flat markdown. Optional `description` frontmatter; the first body line is the fallback. |
+| `agent/skills/<name>.md` | Static Markdown. Optional `description` frontmatter; the first body line is the fallback. |
 | `agent/skills/<name>/SKILL.md` plus siblings | A packaged directory with reference files (`references/…`). Requires `description` frontmatter. |
 | `agent/skills/<name>.ts` | Generated content, with `defineSkill` from `@cursor/july/skills`. |
 
-Flat markdown:
+Use flat Markdown for static content:
 
 ```md
 ---
@@ -7327,8 +7419,8 @@ description: Use when a pull request needs a structured approval checklist.
 3. Call `approve_pr` only after an explicit request; it requires approval.
 ```
 
-TypeScript, when the content must be generated or carry inline sibling
-files:
+Use TypeScript when the content must be generated or include inline
+sibling files:
 
 ```ts
 import { defineSkill } from "@cursor/july/skills";
@@ -7340,40 +7432,29 @@ export default defineSkill({
 });
 ```
 
-## How skills reach the model
-
-On the local runtime, skills land in the session workspace at
-`.cursor/skills/<name>/SKILL.md`, and the harness advertises and loads
-them natively. On the cloud runtime there is no session workspace, so
-the engine copies the same SKILL.md tree onto an Agent Store for native
-discovery:
-
-- Hosted deployments write store-root `skills/<name>/`.
-- `agent-sdk serve` / `run` with a personal `CURSOR_API_KEY` write
-  namespaced skills on the USER store so they cannot collide with the
-  user's own skills.
+## Skill delivery
 
-`validate` still warns about the combination so the store path is
-visible. Cloud turns with neither a hosted store nor an API key see
-only skills already in the cloud repo.
+Local turns receive authored skills automatically. Hosted deployments
+and local `serve` or `run` processes with a personal `CURSOR_API_KEY`
+also make them available to cloud turns. Otherwise, a cloud turn sees
+only skills already in its checkout. `agent-sdk validate` warns when
+`runtime: "cloud"` is combined with authored skills.
 
-## Instructions, skills, or tools?
+## Skills, instructions, and tools
 
 Instructions are always in context: identity, tool-choice rules, the
 output contract. Keep them short. Skills load when relevant: procedures,
 checklists, house style. Reach for a skill when the model needs to
-*follow* something but only sometimes needs it loaded. Tools are typed,
+follow something but only sometimes needs it loaded. Tools are typed,
 executable behavior: anything that must be correct every time belongs in
 tool code, not in prose the model might paraphrase.
 
-A good skill description is a routing rule, not a title. Say *when* to
+A good skill description is a routing rule, not a title. Say when to
 use it, like "Use when a pull request needs a structured approval
 checklist," because the description is all the model sees before
 deciding to load it.
 
-## What's next
-
-Continue with these pages:
+## Related
 
 - [Instructions](/docs/reference/instructions.md): what stays always-on
 - [Tools](/docs/reference/tools.md): when prose needs to become code
@@ -7388,16 +7469,15 @@ Source: /docs/reference/subagents.md
 # Subagents
 
 A subagent is a specialist child agent the model can delegate to
-mid-turn. Each one is its own directory under `agent/subagents/<id>/`,
-with the same `agent.ts` + `instructions.md` shape as the root. On the
-Cursor harness, subagents run as SDK custom subagents: the parent model
-delegates through the harness `task` tool, and the stream records
-`subagent.called` and `subagent.completed`.
+mid-turn. Each one lives under `agent/subagents/<id>/` with a required
+`agent.ts`. Add `instructions.md` or inline `instructions` in `agent.ts`
+for a custom prompt. The parent model delegates through the `task` tool,
+and the stream records `subagent.called` and `subagent.completed`.
 
 ```text
 agent/subagents/researcher/
 ├── agent.ts            # description (required), model (optional)
-└── instructions.md     # the subagent's own system prompt
+└── instructions.md     # optional custom system prompt
 ```
 
 ```ts
@@ -7413,47 +7493,38 @@ export default defineAgent({
 
 ## Subagent rules
 
-`description` is required. It's the only thing the parent model reads
-when deciding whether to delegate, so write it as a routing rule
-("Background research: …"), the same discipline as a
-[skill](/docs/reference/skills.md) description. `model` is optional; omit it to
-inherit the parent's model, or set it to run the specialist on a
-different one.
+`description` is required. The parent model uses it to decide whether
+to delegate, so write it as a routing rule ("Background research: …"),
+following the same discipline as a [skill](/docs/reference/skills.md) description.
+`model` is optional; omit it to inherit the parent's model, or set it
+to run the specialist on a different model.
 
 Subagents inherit the parent's execution surface. Every per-subagent
 capability directory is reported as a warning and ignored: `tools/`,
-`skills/`, `mcp-connections/` (and the legacy `connections/` alias),
-`host-connections/`, `channels/`, `schedules/`, `hooks/`, `sandbox/`,
-and nested `subagents/`.
+`skills/`, `extensions/`, `mcp-connections/`, `host-connections/`,
+`channels/`, `schedules/`, `reminders/`, `hooks/`, `sandbox/`, and
+nested `subagents/`.
 
 Delegation needs both halves: the description makes it possible, and the
 parent's [instructions](/docs/reference/instructions.md) make it happen. "When a
 request needs background research, delegate to the `researcher`
-subagent."
+subagent." The parent routes; the specialist executes.
 
-## Subagent or peer?
+## Subagents and peers
 
 Subagents split one job into roles inside a single agent. When the
 specialist is independently useful, with its own tools, sessions, and
 playground, make it a full agent. See
-[Agent-to-agent](/docs/guides/agent-to-agent.md#peer-or-subagent).
+[Peer agents](/docs/guides/agent-to-agent.md#peer-or-subagent).
 
-## Patterns
-
-Fan-out reviews: a PR-approval agent can delegate to two review
-subagents that read a host-prepared `pr/` evidence tree and report
-prioritized findings, which the parent embeds in its approval comment.
-
-Keep the parent lean: a subagent with focused instructions usually
-works better than a longer parent prompt with conditional sections. The
-parent routes; the specialist executes.
-
-## What's next
-
-Continue with these pages:
+## Related
 
 - [Skills](/docs/reference/skills.md): when a procedure is enough and a child agent
   is overkill
+- [Peer agents](/docs/guides/agent-to-agent.md): independently useful
+  specialists
+- [Agent config](/docs/reference/agent-config.md#harness-tools): `"task"` on the
+  parent's tool allowlist
 
 ---
 
@@ -7464,18 +7535,16 @@ Source: /docs/reference/tools.md
 A tool is a typed action the model can call: hit an API, run a query,
 write a file. Each file in `agent/tools/` defines one tool, and the
 filename becomes the tool name the model sees. Tools come in two
-execution flavors: server tools run in-process on the serve host, and
+execution flavors: server tools run on the serving host, and
 agent tools run as scripts where the agent runs. Every server tool can
 also be called directly, with no model turn.
 
 ## Define a server tool
 
-By default, `execute` runs in-process on the serving host with full
-access to `process.env` and your `agent/lib/` code. Local turns call
-server tools as SDK custom tools. Cloud turns reach them over
-authenticated HTTP MCP back to the serve host when `--public-url` or
-`--cloud-tools-url` is set; without either, the server warns at startup
-and cloud turns omit them.
+By default, `execute` runs on the serving host with full access to
+`process.env` and your `agent/lib/` code. Set `--public-url` or
+`--cloud-tools-url` to make server tools available to cloud turns;
+without either, startup warns and cloud turns omit them.
 
 ```ts
 // agent/tools/inspect_pr.ts
@@ -7498,6 +7567,10 @@ code that runs it. With a Zod `inputSchema`, the input is validated before
 `execute` runs and the input type is inferred. A plain JSON Schema
 object is forwarded as-is and the input arrives as raw JSON.
 
+A server tool can call `decide` from
+[`@cursor/july/extensions/jev`](/docs/guides/jev.md) for a risk tier or a
+finding gate without a second model turn.
+
 For multi-line descriptions, reminder prompts, and error messages, use
 [`prompt`](/docs/reference/prompt.md) so the string can sit indented with the surrounding
 TypeScript:
@@ -7630,7 +7703,7 @@ check nothing.
 ## Define an agent tool
 
 Set `execution: "agent"` and the tool materializes as a shell script
-that runs where the Cursor agent runs: the local harness workspace or
+that runs where the Cursor agent runs: the local session workspace or
 the cloud VM. The script receives JSON arguments on stdin and prints its
 result on stdout. Use this flavor when the tool must run next to the
 checkout the agent works in; on cloud, server tools stay available too
@@ -7653,23 +7726,16 @@ printf '%s\\n' "$message"
 ```
 
 On the local runtime, scripts land in the session workspace with a
-catalog in `AGENTS.md`. On cloud, the catalog and script bodies travel
-on the first prompt.
+catalog in `AGENTS.md`.
 
 ## Tools from an MCP connection, advertised by name
 
-Authored `agent/tools/` files are one catalog for every session. When
-the tools should come from an MCP server, including per-tenant toolsets
-resolved at runtime, declare the connection with
-`advertiseTools: true` (plus per-session `auth` when the credential
-depends on who the session is for) and the engine synthesizes named 1:1
-passthrough server tools from the connection's live `listTools` on every
-local turn. See
-[MCP Connections](/docs/reference/connections.md#advertise-tools).
-Advertised tools ride the same execution path as authored server tools,
-and [direct tool calls](#call-a-tool-without-a-model-turn) address them
-by the same model-facing names: the call's session identity resolves the
-advertised listing when the authored lookup misses.
+Set `advertiseTools: true` on a connection to expose its MCP tools by
+name. Add per-session `auth` when credentials depend on the caller.
+Model calls and [direct tool calls](#call-a-tool-without-a-model-turn)
+use the same exposed names. See
+[MCP connections](/docs/reference/connections.md#advertise-tools) for the full
+contract.
 
 ## Gate a tool on human approval
 
@@ -7700,8 +7766,8 @@ runtime only, and parked calls don't survive a host restart.
 ## Call a tool without a model turn
 
 Server tools can be called deterministically. You pick the tool and the
-input. Validation and execution behave exactly as they would for a
-model-initiated call, and no Cursor API key is needed.
+input. Validation and execution match a model-initiated call, and no
+Cursor API key is needed.
 
 Over HTTP, with the same auth chain as the session API:
 
@@ -7727,51 +7793,43 @@ agent-sdk call inspect_pr \
 Programmatically, `callTool(toolName, input, options?)` is available on
 the serve handle, on channel route handlers and `onStart` args, and on
 schedule `run` handlers, so a channel can mix deterministic calls with
-model turns, fetching PR metadata deterministically and then `send()`ing
-the review prompt:
+model turns:
 
 ```ts
 const outcome = await handle.callTool("inspect_pr", {
   prUrl: "https://github.com/acme/checkout/pull/42",
 });
+if (outcome.isError) {
+  return outcome;
+}
 // { toolName, callId, isError, result, durationMs }
 ```
 
-By default the call runs against an ephemeral workspace and is removed
-when the call returns. Pass a `sessionId` (a body field over
-HTTP, `--session` on the CLI, `options.sessionId` programmatically) to
-run inside an existing session instead: the tool sees that session's
-workspace, and the call is recorded on the session's event stream.
-While a model turn is running, a session-bound call is admitted by its
-effect: a read-effect call (a declared `effect: "read"`, or an advertised
-MCP tool whose server annotates it read-only) runs alongside the turn,
-reading the workspace as the turn has left it, and is recorded under its
-own per-call `turnId` so trajectories keep it apart from the turn's own
-calls; a write-effect call — including an undeclared tool, which counts
-as a write — returns `409 session_busy` until the turn finishes, because
-a running turn owns the workspace. When the
-session's harness cwd cannot be materialized, a read-effect call runs
-in a scratch workspace instead and the outcome carries
-`scratchWorkspace: true`; a write-effect call fails with
-`workspace_unavailable`.
-
-A session can also be addressed by its continuation token: an optional
-`continuationToken` (`<channelId>:<key>`, as `/v1/sessions` lists it;
-mutually exclusive with `sessionId`). A token that maps to a live
-session behaves exactly like passing that session's id — same ownership
-check, same busy semantics, same event recording. A token with no
-session behind it runs the call scratch-bound with the token's channel
-id and continuation key as the call's session identity, so a deployment
-whose tools resolve state from the continuation key can serve it with
-no live session. Malformed tokens are rejected with
-`400 invalid_continuation_token`.
-
-The error semantics match the model path. Unknown tools are rejected
-with the available names, agent-execution tools cannot be called on the
-host (`400`), schema-invalid input is a `400` before the tool body runs
-(Zod validates; plain JSON Schema passes through unvalidated), and a
-tool body that throws reports `isError: true` in the same envelope the
-model would see.
+Omit both identifiers to run against an ephemeral workspace that is
+removed when the call returns. Pass `sessionId` (HTTP body, `--session`,
+or `options.sessionId`) or `continuationToken` (`<channelId>:<key>` as
+`/v1/sessions` lists it) to bind the call. The two are mutually
+exclusive.
+
+| Rule | What happens |
+| --- | --- |
+| Existing `sessionId`, or a token that maps to an existing session | Session workspace, owner check, and event recording |
+| Token with no matching session | Scratch workspace; the token's channel id and key are the call identity |
+| Busy session, `effect: "read"` (or an advertised MCP tool marked read-only) | Runs alongside the turn, reading the workspace as the turn left it; recorded under its own `turnId` |
+| Busy session, write or undeclared | `409 session_busy` until the turn finishes |
+| Session workspace cannot be created, read | Scratch workspace; the outcome has `scratchWorkspace: true` |
+| Session workspace cannot be created, write | `500 workspace_unavailable` |
+
+| Error | When |
+| --- | --- |
+| `404 unknown_tool` | Name is not a callable server tool; the response lists available names |
+| `400 tool_not_callable` | Agent-execution tools cannot run on the host |
+| `400 invalid_tool_input` | Zod rejected the input before `execute`. Plain JSON Schema is forwarded unvalidated |
+| `400 invalid_continuation_token` | Malformed token, or passed together with `sessionId` |
+| `404 session_not_found` | `sessionId` does not exist |
+| `409 session_busy` | Write-effect call while a model turn is running |
+| `500 workspace_unavailable` | Write-effect call when the session workspace cannot be created |
+| `isError: true` | The tool body threw; same envelope the model would see |
 
 ## Design habits
 
@@ -7789,9 +7847,7 @@ wrong, no instruction change fixes it.
 Gate side effects with `needsApproval`. Declare each tool's `effect` so
 dry-run sessions can execute reads and stub writes.
 
-## What's next
-
-Continue with these pages:
+## Related
 
 - [MCP connections](/docs/reference/connections.md): tools that come from MCP servers
   instead
@@ -8399,7 +8455,7 @@ Match the visible symptom below. If `agent-sdk` is not on `PATH`, use
 | File reads and greps fail repeatedly with `NGHTTP2_FRAME_SIZE_ERROR` | Run the agent under Node 22.13 or newer, never Bun. |
 | The turn immediately reports a missing API key | Set `CURSOR_API_KEY`, `CURSOR_API_KEY_FILE`, or `CURSOR_SERVICE_ACCOUNT_KEY`, or run `agent-sdk login`. |
 | Login succeeds but the model host rejects the key | Point login and model traffic at the same API host; check `CURSOR_API_BASE_URL` and `CURSOR_BACKEND_URL`. |
-| Cloud turns cannot reach local tools or skills | Give the cloud runtime a reachable `--public-url` and protected tool bridge, or move the required capability into the cloud checkout. See [agent runtime](/docs/reference/agent-config.md#choose-a-runtime). |
+| Cloud turns cannot reach local tools or skills | Give the cloud runtime a reachable `--public-url` and protected tool bridge, or move the required capability into the cloud checkout. See [agent runtime](/docs/reference/agent-config.md#runtime). |
 
 ## A turn behaves unexpectedly