@cursor/july 0.1.109 → 0.1.112

package/docs/reference/extensions.md

@@ -1,212 +1,167 @@
 ---
 title: "Extensions"
-description: "Mount a package of agent contributions or a Cursor plugin under a namespace with one file, adjust what it contributes, and author your own as a directory laid out like agent/."
+description: "Mount a namespaced package of tools, skills, connections, and other agent capabilities, then inspect or override what it adds."
 ---
 
 # Extensions
 
-An extension packages the same contributions an agent authors under
-`agent/` and installs them as one unit. You mount it with a single file
-under `agent/extensions/`, and its contributions join the agent under a
-namespace. The package updates like any other dependency; nothing is
-copied into your project. A Cursor plugin mounts the same way; see
-[Mount a Cursor plugin](#mount-a-cursor-plugin).
+An extension packages capabilities that would otherwise live under
+`agent/`: tools, skills, instructions, connections, hooks, channels,
+schedules, subagents, artifacts, and workspace seeds. One mount file
+adds them under a namespace without copying their source into your
+project.
 
-Extensions are native to the Agent SDK. Slot files use the `@cursor/july`
-helpers, so a package built on another agent framework fails
-`agent-sdk validate` until you rewrite it onto `@cursor/july`.
+Extensions and Cursor plugins execute as trusted host code. A namespace
+prevents name collisions; it does not sandbox the package or limit its
+side effects. Review the package before mounting it.
 
 ## Mount an extension
 
-Install the package, then add one file. The filename is the namespace.
+Install the package and add one file under `agent/extensions/`. The
+filename becomes the namespace, so this mount contributes names such as
+`ci__failed_jobs` and `ci__triage`.
 
 ```ts
 // agent/extensions/ci.ts
 import ci from "@acme/ci-triage";
 
-export default ci({ org: "acme", token: process.env.BUILDKITE_TOKEN! });
+export default ci({
+  org: "acme",
+  token: process.env.BUILDKITE_TOKEN,
+});
 ```
 
-Every contribution is exposed as `<namespace>__<name>`. A `failed_jobs`
-tool from this mount runs in the agent as `ci__failed_jobs`, and a
-`triage` skill loads as `ci__triage`. `agent-sdk info` lists each mount
-with what it contributed, and `GET /v1/info` returns the same under
-`extensions`.
+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.
 
-Pass the configuration the extension asks for. The extension validates it
-when the agent loads, so a missing or mistyped field fails
-`agent-sdk validate` instead of a tool call later.
+Extension instructions are appended to the agent's prompt. The root
+agent still needs its own `agent/instructions.md`.
 
-Namespaces follow the tool-name rule, and `__` is reserved: an authored
-`agent/tools/ci__failed_jobs.ts` fails discovery, so nothing outside a
-mount can pose as one of its tools.
+## See what the extension added
 
-## What an extension can contribute
+Run discovery after mounting or upgrading an extension:
 
-An extension tree uses the same slots as [`agent/`](./project-layout.md).
-Each shareable contribution lands on the agent under the mount's
-namespace:
+```bash
+agent-sdk validate --dir .
+agent-sdk info --dir . --json
+```
+
+`info` lists each mount and its namespaced tools, skills, connections,
+hooks, channels, schedules, subagents, and artifact kinds. The same
+data appears under `extensions` in `GET /v1/info`.
 
-| Path | Becomes |
-| --- | --- |
-| `tools/<name>.ts` | tool `<ns>__<name>` |
-| `skills/<name>` | skill `<ns>__<name>` |
-| `mcp-connections/<name>.ts` | connection `<ns>__<name>` |
-| `host-connections/<name>.ts` | host connection `<ns>__<name>` |
-| `hooks/<name>.ts` | hook `<ns>__<name>` |
-| `channels/<name>.ts` | channel `<ns>__<name>` |
-| `schedules/<name>` | schedule `<ns>__<name>` |
-| `subagents/<id>/` | subagent `<ns>__<id>` |
-| `instructions.md` / `.ts` / dir | appended to the agent's system prompt |
-| `sandbox/workspace/**` | seeded into each local session workspace |
-| `artifacts.ts` | artifact kinds `<ns>__<kind>` |
-
-The root agent still needs its own `instructions.md`. Extension
-instructions are extra fragments, not a substitute.
-
-`httpChannel()` stays on the agent. An extension authors
-`defineChannel` only; a file named `http.ts` becomes `<ns>__http`.
-
-These stay on the agent that mounts the extension. Each is a singleton
-or is outside discovery:
-
-| Path | Why it stays on the agent |
-| --- | --- |
-| `agent.ts` | One `defineAgent` runtime per agent |
-| `storage.ts` | One `host.kv` / `host.files` backend |
-| `otel.ts` | One OTLP exporter |
-| `playground/` | Custom chips are a Vite glob of the agent tree, not a discovery walk |
-| `extensions/` | Nested mounts are not loaded |
-| `sandbox.ts` | Custom sandbox backends stay on the agent |
-
-`agent-sdk validate` warns when a tree carries those paths.
+Names inside the extension stay short. A tool authored as
+`tools/failed_jobs.ts` appears to the mounting agent as
+`<namespace>__failed_jobs`. The `__` separator is reserved, so root
+contributions cannot impersonate a mounted one.
 
 ## Adjust a mounted extension
 
-To replace or remove a contribution, mount the extension as a directory
-and overlay the slot you want to change.
+Mount as a directory when you need to replace or remove one
+contribution. Keep the package mount in `extension.ts`, then overlay the
+extension's short name beneath it.
 
 ```text
 agent/extensions/ci/
-├── extension.ts        # the mount: export default ci({ ... })
-├── tools/
-│   ├── job_log.ts      # replaces ci__job_log with your own defineTool
-│   └── retry_job.ts    # export default disableTool() removes ci__retry_job
-├── hooks/
-│   └── audit.ts        # export default disableHook() removes ci__audit
-└── skills/
-    └── triage.ts       # export default disableSkill() removes ci__triage
+  extension.ts
+  tools/
+    job_log.ts
+    retry_job.ts
+```
+
+```ts
+// agent/extensions/ci/tools/job_log.ts
+import { defineTool } from "@cursor/july/tools";
+import {
+  jobLogInput,
+  readRedactedLog,
+} from "../../../lib/ci.js";
+
+export default defineTool({
+  description: "Read a redacted CI log.",
+  inputSchema: jobLogInput,
+  execute: readRedactedLog,
+});
+```
+
+```ts
+// agent/extensions/ci/tools/retry_job.ts
+import { disableTool } from "@cursor/july/extensions";
+
+export default disableTool();
 ```
 
-Use the extension's own names inside the directory, without the
-namespace. A file with a name the extension doesn't contribute adds a
-new contribution under the namespace. Each helper comes from
-`@cursor/july/extensions` and fails discovery when it names a
-contribution the extension doesn't have, so a typo can't silently keep
-it alive.
-
-| Slot | Helper |
-| --- | --- |
-| `tools/<name>.ts` | `disableTool()` |
-| `mcp-connections/<name>.ts` / `host-connections/<name>.ts` | `disableConnection()` |
-| `skills/<name>.ts` | `disableSkill()` |
-| `hooks/<name>.ts` | `disableHook()` |
-| `channels/<name>.ts` | `disableChannel()` |
-| `schedules/<name>.ts` | `disableSchedule()` |
-| `subagents/<id>.ts` | `disableSubagent()` |
-| `instructions.ts` | `disableInstructions()` |
-| `artifacts.ts` | `disableArtifacts()` |
-
-`disable()` is the same brand as the slot helpers above and works in
-any of those files.
-
-A Cursor plugin mount overlays its MCP servers the same way; see below.
+The first file replaces `ci__job_log`; the second removes
+`ci__retry_job`. Use the matching `disable*` helper for another slot, or
+generic `disable()` when the file location already identifies it.
+Validation fails when an overlay names a contribution the package does
+not provide.
 
 ## Mount a Cursor plugin
 
-A Cursor plugin is a directory with `.cursor-plugin/plugin.json` (or
-`.claude-plugin/plugin.json`, or `plugin.json`) and any of `skills/`,
-`commands/`, `agents/`, and `mcp.json`. Copy the plugin into your project
-and mount it with `cursorPlugin`. The filename is the namespace, as with
-any extension.
+`cursorPlugin()` adapts a vendored Cursor or Claude plugin into the same
+namespace model. Skills, commands, agents, and MCP servers become Agent
+SDK skills, subagents, and connections.
 
 ```ts
 // agent/extensions/notion.ts
 import { cursorPlugin } from "@cursor/july/extensions";
 
 export default cursorPlugin({
-  path: "plugins/notion-workspace", // relative to the project root
-  variables: { NOTION_TOKEN: process.env.NOTION_TOKEN! },
+  path: "plugins/notion-workspace",
+  variables: {
+    NOTION_TOKEN: process.env.NOTION_TOKEN,
+  },
 });
 ```
 
-The plugin joins the agent under that namespace:
-
-| Plugin content | Becomes |
-| --- | --- |
-| `skills/<name>/SKILL.md` | skill `notion__<name>` |
-| `commands/<name>.md` | skill `notion__<name>`, since a command is a procedure the model runs on request |
-| `agents/<name>.md` | subagent `notion__<name>` |
-| MCP servers in `mcp.json` or the manifest | connection `notion__<server>` |
-
-`variables` fills the `${NAME}` placeholders the plugin's MCP config
-declares; names you leave out come from the environment by exact name. A
-placeholder nothing fills fails `agent-sdk validate`, so a server never
-attaches half configured. A server that declares an OAuth client
-authorizes through [host MCP OAuth](../guides/mcp-oauth.md) as
-`agent-sdk mcp oauth notion__<server>`; its secret names collapse the
-namespace separator, so `notion__notion` stores `MCP_OAUTH_NOTION_NOTION_*`.
-A server that lists `enabledTools` mounts as an advertised connection with
-that allowlist and requires the local runtime; `agent-sdk validate` fails
-otherwise.
-
-Mounting a plugin trusts it like authored code: its servers run the
-commands and read the environment variables its config names. Review a
-plugin before you vendor it.
-
-Plugin rules and hooks are not mounted; `agent-sdk validate` warns when a
-plugin carries them. To drop or reconfigure one of the plugin's servers,
-mount as a directory and overlay `mcp-connections/<server>.ts`. An
-overlaid server is never read from the plugin, so it needs no variables.
+`path` is relative to the project root. `variables` fills placeholders
+declared by the plugin's MCP configuration; unresolved placeholders
+fail validation instead of mounting a partial server.
 
-```text
-agent/extensions/cloudflare/
-├── extension.ts                        # export default cursorPlugin({ path: "plugins/cloudflare" })
-└── mcp-connections/
-    ├── cloudflare-docs.ts              # replaces cloudflare__cloudflare-docs with your defineConnection
-    └── cloudflare-bindings.ts          # export default disableConnection() drops it
-```
+Plugin rules and hooks are not mounted. Overlay a generated
+`mcp-connections/<server>.ts` file to replace or disable one plugin
+server. OAuth-backed plugin servers use
+[Host MCP OAuth](../guides/mcp-oauth.md); transport and tool-filter
+details live in [MCP connections](./connections.md).
+
+## What an extension can contain
 
-`disableConnection()` comes from `@cursor/july/extensions` and fails
-discovery when it names a server the plugin doesn't declare.
+Share capabilities that can safely join another agent under a
+namespace:
+
+- Instructions, tools, skills, MCP and host connections
+- Hooks, channels, schedules, and subagents
+- Artifact kinds and local workspace seed files
+
+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
 
-An extension is a directory laid out like `agent/`. `extension.ts`
-declares it; the slots in [What an extension can contribute](#what-an-extension-can-contribute)
-use the same authoring forms as the rest of this reference.
+Lay out the package like the shareable part of `agent/`. The root
+`extension.ts` supplies a description and validates any settings the
+consumer must provide.
 
 ```text
 @acme/ci-triage/
-├── package.json
-├── extension.ts        # defineExtension
-├── tools/
-│   ├── failed_jobs.ts
-│   ├── job_log.ts
-│   └── retry_job.ts
-├── skills/
-│   └── triage.md
-├── hooks/
-│   └── audit.ts
-├── mcp-connections/
-│   └── buildkite.ts
-└── lib/
-    └── buildkite.ts    # shared code, never discovered
+  package.json
+  extension.ts
+  instructions.md
+  tools/
+    failed_jobs.ts
+    job_log.ts
+  skills/
+    triage.md
+  hooks/
+    audit.ts
+  lib/
+    buildkite.ts
 ```
 
-Declare the extension with its root and, when consumers must configure
-it, a schema for their settings.
-
 ```ts
 // extension.ts
 import { defineExtension } from "@cursor/july/extensions";
@@ -214,7 +169,7 @@ import { z } from "zod";
 
 export default defineExtension({
   root: import.meta.dirname,
-  description: "Investigate failing CI builds on Buildkite.",
+  description: "Investigate failing Buildkite jobs.",
   config: z.object({
     org: z.string(),
     token: z.string(),
@@ -223,48 +178,21 @@ export default defineExtension({
 });
 ```
 
-The default export is what consumers call to mount the extension, and it
-is also how your own modules read the consumer's settings. Import it and
-read `extension.config`; the value is validated and has defaults applied.
+Modules inside the package import this definition and read
+`extension.config`, which is already validated and has defaults
+applied. Publish the built entry point with its slot directories and
+prose assets beside it.
 
-```ts
-// tools/job_log.ts
-import { defineTool } from "@cursor/july/tools";
-import { z } from "zod";
-import extension from "../extension.js";
-import { jobLogTail } from "../lib/buildkite.js";
+The [Project layout](./project-layout.md) owns each contribution's
+authoring contract. Keep extension instructions and tool descriptions
+namespace-neutral because the consumer chooses the final prefix.
 
-export default defineTool({
-  description: "Read the tail of a CI job's log.",
-  effect: "read",
-  inputSchema: z.object({ pipeline: z.string(), build: z.number(), job: z.string() }),
-  async execute({ pipeline, build, job }) {
-    const { org, token, logTailLines } = extension.config;
-    return jobLogTail({ org, token, pipeline, build, job, lines: logTailLines });
-  },
-});
-```
+## Related
 
-Because the consumer picks the namespace, have skills and tool
-descriptions refer to sibling tools by their short names and say they
-appear under the mount's namespace (`<namespace>__job_log`).
-
-Publish the built `extension.js` as the package entry point with the
-slot directories beside it. `root` is read from the built file, so copy
-`skills/*.md` and `instructions.md` into the build output or author them
-as `.ts`.
-
-## What's next
-
-Continue with these pages:
-
-- [Cursor cloud agents](../guides/cloud-agents.md): the extension that
-  lets an agent launch and steer cloud agents
-- [Cursor Grok Bot agents](../guides/grokbot-agents.md): the extension
-  that lets an agent talk to Grok Bot agents
-- [Self-improvement](../guides/improve.md): the extension that lets an
-  agent change its own source through a cloud agent and a pull request
-- [Tools](./tools.md): the tool contract extensions contribute to
-- [Skills](./skills.md): the skill forms an extension can carry
-- [Project layout](./project-layout.md): where `agent/extensions/` sits
-  in the tree
+- [Cloud agents](../guides/cloud-agents.md): delegate repository work
+  through an extension
+- [Grok Bot agents](../guides/grokbot-agents.md): consult named bots
+- [Self-improvement](../guides/improve.md): propose source changes
+  through pull requests
+- [Project layout](./project-layout.md): contribution slots
+- [Tools](./tools.md) and [Skills](./skills.md): capability contracts

package/docs/reference/hooks.md

@@ -73,31 +73,31 @@ stream envelope `{ type, index, sessionId, turnId?, at, data }`, with
 
 The payloads hooks read most often:
 
-| 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 |
+| 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                                                                                   |
 
 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](../storage.md#author-kv-ctx-host-kv) decides whether it survives a hosted replace. Prefix keys with `ctx.session.id` for per-session state |
-| `ctx.host.files` | Durable files, bound to this session. Pass `{ scope: "deployment" }` for agent-wide files |
-| `ctx.host.otel` | Counters, histograms, and tags, attributed to this session |
-| `ctx.host.mcp`, `ctx.host.github`, `ctx.host.slack` | The same shared clients tools get |
-| `ctx.host.reminders` | Per-session [reminders](./schedules.md), the same API tools get |
-| `ctx.artifacts` | Session-bound [artifacts](./artifacts.md) facade: `tag` fills in `sessionId` and `turnId` |
-| `ctx.stateRoot` | Absolute path of the local state root. It resets when a hosted deployment is replaced; keep derived state in `kv` or `files` |
+| Member                                              | What it is                                                                                                                                                                    |
+| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ctx.session`                                       | Read-only session info: `id`, `channelId`, `mode` (`chat` or `task`), `purpose` (`live` or `eval`), `auth`, plus `title` and `sdkAgentId` when set                            |
+| `ctx.agent`                                         | `{ name }` of the agent the event belongs to                                                                                                                                  |
+| `ctx.channel`                                       | `{ id, continuationToken }`. The token is `null` when the session can't take follow-ups                                                                                       |
+| `ctx.host.kv`                                       | Durable JSON, shared by every session of the agent; the storage backend decides whether it survives a hosted replace. Prefix keys with `ctx.session.id` for per-session state |
+| `ctx.host.files`                                    | Durable files, bound to this session. Pass `{ scope: "deployment" }` for agent-wide files                                                                                     |
+| `ctx.host.otel`                                     | Counters, histograms, and tags, attributed to this session                                                                                                                    |
+| `ctx.host.mcp`, `ctx.host.github`, `ctx.host.slack` | The same shared clients tools get                                                                                                                                             |
+| `ctx.host.reminders`                                | Per-session [reminders](./schedules.md), the same API tools get                                                                                                               |
+| `ctx.artifacts`                                     | Session-bound [artifacts](./artifacts.md) facade: `tag` fills in `sessionId` and `turnId`                                                                                     |
+| `ctx.stateRoot`                                     | Absolute path of the local state root. It resets when a hosted deployment is replaced; keep derived state in `kv` or `files`                                                  |
 
 ## When hooks run
 
@@ -123,24 +123,24 @@ the hook's copy is the source of truth.
 
 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` |
+|                    | 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 [Show PR progress](../guides/github.md#show-pr-progress) |
-| Block, approve, or rewrite a tool call | [`needsApproval`](./tools.md#gate-a-tool-on-human-approval) on the tool |
-| Act on the final assistant text, or fail a bad turn | [`defineResult`](./result.md) |
-| Gate a change on behavior | [Evals](../evals.md) |
+| You want to                                                                           | Use instead                                                                                                      |
+| ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| Add context before the model runs                                                     | The channel's `send` message and `workspaceFiles`, `instructions.md`, skills, or `sandbox/workspace/` seed files |
+| Reply on Slack, comment on a PR, or post any other delivery                           | The channel's `events` map, or the Slack and GitHub packs                                                        |
+| Show PR progress (merge-box check, sticky banner)                                     | `githubChannel({ progress: { commitStatus, banner } })`; see the [PR autofixer](../templates/pr-autofixer.md)    |
+| Block, approve, or rewrite a tool call                                                | [`needsApproval`](./tools.md#gate-a-tool-on-human-approval) on the tool                                          |
+| Act on the final assistant text, reject it for a same-turn repair, or fail a bad turn | `defineResult`                                                                                                   |
+| Gate a change on behavior                                                             | [Evals](../evals.md)                                                                                             |
 
 ## Patterns
 
@@ -258,9 +258,7 @@ At runtime:
 
 Continue with these pages:
 
-- [Turn result](./result.md): fail a turn from `commit`, not from a hook
 - [Sessions and streaming](./sessions.md): the event vocabulary hooks observe
-- [Storage](../storage.md): where `ctx.host.kv` and `ctx.host.files` live
 - [OpenTelemetry](../guides/opentelemetry.md): OTLP traces and metrics
   from the same event stream
 - [Deployment](../deployment.md#observability): runtime logs and export

package/docs/reference/http-api.md

@@ -118,7 +118,7 @@ Two routes list and resolve parked tool calls.
 | `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"}` |
 
-For the lifecycle, see [Human-in-the-loop](../guides/human-in-the-loop.md).
+For the lifecycle, see [Gate a tool on human approval](./tools.md#gate-a-tool-on-human-approval).
 
 ## Call a tool directly
 
@@ -189,8 +189,8 @@ secret is configured. See [Channels](./channels.md).
 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. See
-[Agent-to-agent](../guides/agent-to-agent.md).
+route runs the same auth chain as the session API. Peer wiring:
+[MCP connections](./connections.md#peer-mcp-connection).
 
 `/v1/mcp/tools` is a second stateless MCP endpoint exposing only the
 agent's deterministic server tools. Hosted cloud turns call back into
@@ -214,8 +214,8 @@ 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 storage is configured; see
-[Storage](../storage.md#eval-table). Otherwise they are
+entry from each field. Listed runs persist across restarts when
+durable storage is configured. Otherwise they are
 process-memory only.
 
 ## Dev-mode routes

package/docs/reference/playground.md

@@ -57,5 +57,5 @@ Continue with these pages:
 
 - [HTTP API](./http-api.md): the HTTP surface the playground uses
 - [Sessions and streaming](./sessions.md): the streams it renders
-- [Human-in-the-loop](../guides/human-in-the-loop.md): the approval
-  buttons in context
+- [Gate a tool on human approval](./tools.md#gate-a-tool-on-human-approval):
+  the approval buttons in context

package/docs/reference/project-layout.md

@@ -73,10 +73,10 @@ 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](./extensions.md) |
 | `agent/channels/*.ts` | HTTP surfaces beyond the built-in session API; `slack.ts` and `github.ts` use the platform packs | [Channels](./channels.md) |
 | `agent/hooks/*.ts` | Observe-only event subscribers, never fatal | [Hooks](./hooks.md) |
-| `agent/otel.ts` | `defineOtel` OTLP export (traces, metrics, optional logs) | [OpenTelemetry](../guides/opentelemetry.md) |
-| `agent/storage.ts` | `defineStorage` backend for the durable `host.kv` / `host.files` APIs | [Storage](../storage.md) |
+| `agent/otel.ts` | Factory-only OTLP authoring (`defineOtel`). Public path is env / `serve({ otel })`. | [OpenTelemetry](../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](./artifacts.md) |
-| `agent/result.ts` | `defineResult` host `commit` on the final assistant text | [Turn result](./result.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](./schedules.md) |
 | `agent/sandbox/workspace/**` | Seed files copied into each local session workspace | [Sessions](./sessions.md#what-goes-into-a-local-session-workspace) |
 | `agent/playground/` | Custom playground tool chips | [Playground](./playground.md) |
@@ -110,4 +110,3 @@ Continue with these pages:
 
 - [Agent config](./agent-config.md): the runtime config at the root
 - [Tools](./tools.md): add typed actions under `agent/tools/`
-- [Concepts](../concepts.md): why the filesystem is the interface

package/docs/reference/sessions.md

@@ -95,8 +95,10 @@ 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` or empty assistant text emits `turn.failed` instead of
-`turn.completed`. See [Turn result](./result.md).
+`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.
 
 ## How do I stream or replay session events?
 
@@ -146,7 +148,7 @@ Cloud conversations remain on the Cursor backend.
 
 Nested git checkouts already default `local.cwd` outside the enclosing
 repo. See
-[local session workspaces](../concepts.md#what-files-can-a-local-session-access).
+[What goes into a local session workspace?](#what-goes-into-a-local-session-workspace).
 
 ## How do I inspect a saved event stream?
 
@@ -164,4 +166,3 @@ view.
 
 - [HTTP API](./http-api.md)
 - [Hooks](./hooks.md)
-- [How the Agent SDK works](../concepts.md)

package/docs/reference/subagents.md

@@ -53,9 +53,8 @@ subagent."
 
 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 and wire a peer MCP connection instead. The
-comparison table is in the
-[Agent-to-agent guide](../guides/agent-to-agent.md#peer-or-subagent).
+playground, make it a full agent. See
+[Agent-to-agent](../guides/agent-to-agent.md#peer-or-subagent).
 
 ## Patterns
 
@@ -71,6 +70,5 @@ parent routes; the specialist executes.
 
 Continue with these pages:
 
-- [Agent-to-agent](../guides/agent-to-agent.md): the peer alternative
 - [Skills](./skills.md): when a procedure is enough and a child agent
   is overkill