@cursor/july 0.1.43 → 0.1.46

package/docs/guides/github.md

@@ -44,12 +44,14 @@ Choose `permissions` by what the agent needs:
 | --- | --- |
 | `"read"` | Inspect PRs / issues / statuses only |
 | `"pr-write"` (default) | Comment, review, update PR/issue metadata |
-| `"contents-write"` | Push code, or create commit statuses |
+| `"contents-write"` | Push code, or post merge-box checks |
 
-`contents-write` is an explicit opt-up. Creating a commit status needs
-push-equivalent access (`contents:write`); `pr-write` alone can write
-comments and banners but not merge-box checks. Prefer `"pr-write"` unless
-the agent must push or post commit statuses.
+`contents-write` is an explicit opt-up. `progress.commitStatus` posts a
+GitHub check run (`checks:write`). Hosted `cursorAccount` mints that
+permission on `"contents-write"` tokens. Enabling `commitStatus` opts a
+`"pr-write"` channel up to that tier so github-proxy can post the check.
+`"pr-write"` without `commitStatus` is enough for comments and banners.
+Prefer `"pr-write"` unless the agent must push or post a merge-box check.
 
 Selected repositories must share one GitHub owner (one App installation).
 Configuration that spans owners fails at startup / mint time.
@@ -206,7 +208,7 @@ Autofix-style agents need a deterministic merge-box check and a sticky
 PR comment that converges when the turn ends. Configure that on the
 channel with `progress.commitStatus` and `progress.banner`. A hook can
 read and write `ctx.host.kv` and `ctx.host.files` after a turn. Use
-that for derived state. Keep GitHub status and banner writes on the
+that for derived state. Keep GitHub check-run and banner writes on the
 channel.
 
 ```ts
@@ -229,10 +231,11 @@ export default githubChannel({
       failure: "Autofix failed",
     },
   },
-  // commitStatus needs contents-write (push-equivalent). Banner works on pr-write.
+  // commitStatus posts a Checks API run. Hosted cursorAccount opts the
+  // minted token up to contents-write (checks:write). Banner also works
+  // on pr-write without commitStatus.
   cursorAccount: {
     repos: ["owner/repo"],
-    permissions: "contents-write",
   },
   onPullRequest: (ctx, pr) =>
     pr.action === "opened" ? { auth: defaultGitHubAuth(ctx) } : null,
@@ -241,26 +244,28 @@ export default githubChannel({
 
 Default stream events drive the lifecycle:
 
-| Event | Commit status | Banner |
+| Event | Check run | Banner |
 | --- | --- | --- |
-| `turn.started` | `pending` | create (or keep) the sticky comment |
-| `turn.completed` | `success` | PATCH the same comment |
-| `turn.failed` / `session.failed` | `failure` | PATCH the same comment |
+| `turn.started` | `in_progress` | create (or keep) the sticky comment |
+| `turn.completed` | `completed` / `success` | PATCH the same comment |
+| `turn.failed` / `session.failed` | `completed` / `failure` | PATCH the same comment |
 
 Omit `commitStatus` / `banner`, or set them to `false`, to keep today's
 behavior. Reactions still default on; set `reactions: false` when the
 eyes emoji is noise. Descriptions are optional; defaults derive from
-`botName` or the status `context`.
+`botName` or the check `context`.
 
-Commit status posts to `channel.state.headSha`. PR and CI wakes seed and
+The check run posts to `channel.state.headSha`. PR and CI wakes seed and
 refresh it (`refreshState` on continuation). A first wake that is only an
-`issue_comment` has no head SHA in the payload, so status is skipped until
+`issue_comment` has no head SHA in the payload, so the check is skipped until
 a PR/CI wake stores one; the banner still posts. Review-comment wakes
 carry `pull_request.head.sha` when GitHub includes it.
 
-The sticky comment id lives on durable `GitHubChannelState` (session
-record). Each wake also passes `refreshState` so `headSha` / refs update
-on continuation without wiping that id. Persist other derived state
+The sticky comment id and latest check-run id live on durable
+`GitHubChannelState` (session record). Each wake also passes `refreshState`
+so `headSha` / refs update on continuation without wiping those ids. A later
+turn on the same SHA creates a new check run — GitHub cannot reopen a
+completed run. Persist other derived state
 with `ctx.host.kv` or `ctx.host.files`. `stateRoot` resets on hosted
 replace.
 

package/docs/guides/opentelemetry.md

@@ -131,6 +131,36 @@ Shared names (same keys as enterprise export):
 Agent SDK only (`agent_sdk.*`): agent name, turn id, channel, call id,
 subagent name, session mode, and HTTP duration (`agent_sdk.http.duration`).
 
+## How do I emit my own metrics?
+
+`ctx.host.otel` is always present on tools, hooks, and channel
+handlers. Counters and histograms no-op when no meter is running.
+`setAttributes` still tags the open session when a collector is
+attached.
+
+Prefix metric names with your team or agent. First-party names
+(`cursor.token.usage`, `cursor.tool.calls`, `cursor.cost.usage`,
+`agent_sdk.session.count`, `agent_sdk.turn.count`,
+`agent_sdk.subagent.count`, `agent_sdk.http.duration`) and join keys
+(`cursor.conversation.id`, `agent_sdk.agent`, `agent_sdk.turn_id`,
+`agent_sdk.framework`) are reserved. Custom spans are not on this
+surface.
+
+```ts
+ctx.host.otel.setAttributes({
+  "abc.ticket_id": "INC-123",
+  "abc.queue": "p1",
+});
+ctx.host.otel.increment("abc.ticket.resolved");
+ctx.host.otel.record("abc.approval.duration_ms", 1420, {
+  outcome: "approved",
+});
+```
+
+A session-bound host (tools and hooks) adds `cursor.conversation.id`
+and `agent_sdk.agent` for you. Tags merge: later `setAttributes` calls
+paint open spans and later first-party metrics.
+
 ## What stays off the OpenTelemetry wire?
 
 User prompts, tool arguments, tool results, and failure messages are

package/docs/quickstart.md

@@ -1,29 +1,27 @@
 ---
-title: "Build your first PR approver"
-description: "Create an agent that reviews pull requests by complexity, approves the safe ones, and wakes from GitHub webhooks."
+title: "Build your first PR reviewer"
+description: "Create an agent that reviews pull requests by complexity, approves safe changes, and handles GitHub webhook events."
 ---
 
-# Build your first PR approver
+# Build your first PR reviewer
 
-Build an agent that reviews GitHub pull requests. It fetches the diff,
-rates the change's complexity in plain TypeScript, approves the safe
-ones, and flags the rest for a human. Then wire it to GitHub webhooks
-and watch a pull request wake it.
+Build a GitHub PR reviewer that classifies changes as `trivial`,
+`moderate`, or `large`, then approves safe changes or requests human
+review. Add GitHub event handling so pull requests can trigger reviews.
 
-The split is the point of the exercise: deterministic policy lives in
-typed tools, judgment lives in the model, and every decision is
-inspectable in the playground.
+## Getting started
 
-## Prerequisites
+- **Get started with an agent in Cursor:** follow
+  [Scaffold an agent with Cursor](./scaffolding-agents.md) and ask Cursor
+  to read [`skills/create-agent/SKILL.md`](../skills/create-agent/SKILL.md).
+- **Get started in the CLI:** continue below.
 
-You need:
+## Prerequisites
 
 - Node 22.13 or newer. Bun isn't supported.
-- The `agent-sdk` CLI. `npx @cursor/july init ./pr-approver` bootstraps
-  it with no prior install: `init` scaffolds the project, runs
-  `npm install`, links `agent-sdk` onto your PATH, and offers a Cursor
-  sign-in. See [Run the CLI](/#run-the-cli) for other setups, such as a
-  monorepo source checkout.
+- Run commands as `agent-sdk <command>`, or use
+  `npx @cursor/july <command>` when the CLI isn't on `PATH`. See
+  [Run the CLI](/#run-the-cli) for monorepo checkouts and other setups.
 - A Cursor credential for model turns. Sign in once:
 
 ```bash
@@ -32,122 +30,33 @@ agent-sdk login
 
 You can also set `CURSOR_API_KEY` instead of signing in.
 
-- A GitHub credential. `gh auth login` is enough, or set
-  `GITHUB_TOKEN`. The tools you write resolve either one
-  automatically. Reading pull requests works on any public repo;
-  posting reviews needs write access to the repo you review.
+- Authenticate with `gh auth login` or `GITHUB_TOKEN`. You can read
+  public pull requests. Posting reviews requires repository write access.
 
-## First run in 10 minutes
+## Create and run the project
 
-Want a working agent before the full tutorial? Four commands get you
-there:
+Initialize the project and start the development server:
 
 ```bash
-npx @cursor/july init ./pr-approver     # scaffold + npm install + PATH link + sign-in offer
-cd pr-approver
-agent-sdk dev                           # serve, and print the playground URL
-```
-
-Open the playground URL and chat with the scaffold. Then, in a second
-terminal (`dev` keeps running), run one turn from the command line:
-
-```bash
-agent-sdk run --dir . --message "Introduce yourself in one sentence."
-```
-
-That's the whole loop: files become an agent, `dev` serves it, and
-`run` exercises it. The rest of this page turns that scaffold into a
-real PR approver.
-
-## Scaffolding Agents
-
-Have Cursor read [`skills/create-agent/SKILL.md`](../skills/create-agent/SKILL.md)
-and describe what you want:
-
-> Build me a PR approver for the playground. Start with one tool that
-> inspects a pull request and guide me through the remaining decisions.
-
-Cursor asks for missing choices, shows you the plan, then builds and
-verifies the agent. Continue below to do the same by hand.
-
-See [Scaffold an agent with Cursor](./scaffolding-agents.md) for the
-full guided workflow.
-
-## Create your project
-
-Start with the built-in scaffold:
-
-```bash
-npx @cursor/july init ./pr-approver
-cd pr-approver
+npx @cursor/july init ./sdk-pr-reviewer
+cd sdk-pr-reviewer
 agent-sdk dev
 ```
 
-The scaffold creates the files the Agent SDK discovers, plus empty capability
-folders (each with a `.gitkeep`) so you can drop tools, channels, and
-evals in place:
-
-```text
-pr-approver/
-├── agent/
-│   ├── agent.ts
-│   ├── instructions.md
-│   ├── tools/
-│   │   └── echo.ts
-│   ├── skills/
-│   ├── mcp-connections/
-│   ├── subagents/
-│   ├── channels/
-│   ├── hooks/
-│   │   └── memory.ts
-│   ├── ab/
-│   ├── schedules/
-│   ├── sandbox/workspace/
-│   └── lib/
-├── evals/
-├── package.json
-└── tsconfig.json
-```
-
-`agent.ts` holds the model and runtime settings. `instructions.md` is
-the always-on system prompt, and the scaffold's version includes a
-memory section that tells the agent how to consult its journal. Each
-file under `agent/tools/` becomes a tool, and `agent/hooks/memory.ts`
-journals every turn so future sessions can recall past work (delete it
-to opt out). `tsconfig.json` type-checks the project (`npm run check`);
-the framework runs your TypeScript directly, so nothing compiles.
-
-`agent-sdk dev` blocks until you stop it. Keep it running and open a
-second terminal for every other command on this page, starting with
-these checks:
+Keep `agent-sdk dev` running. In a second terminal, run:
 
 ```bash
-agent-sdk validate --dir .
-agent-sdk info --dir .
-```
-
-These commands inspect the project without starting a model turn.
-
-## Run your agent
-
-The scaffold already works. Run one turn from the terminal:
-
-```bash
-agent-sdk run --dir . \
-  --message "Introduce yourself in one sentence."
+agent-sdk run --dir . --message "Introduce yourself in one sentence."
 ```
 
-`run` starts the agent, sends the message, and waits for the final
-reply. It prints a JSON trajectory with the response, tool calls, and
-token usage. It also writes an NDJSON trace under
-`.agent-serve/traces/`.
+Confirm the agent replies.
 
-## Teach it to review
+## Add review instructions
 
 Replace `agent/instructions.md`:
 
 ```md
-# PR approver
+# PR reviewer
 
 You review GitHub pull requests. Be specific and brief.
 
@@ -178,9 +87,6 @@ rm agent/tools/echo.ts
 
 ## Add a shared helper
 
-Both tools need to split a PR URL into its parts. Shared code lives in
-`agent/lib/`, which the framework never loads as tools.
-
 Create `agent/lib/github.ts`:
 
 ```ts
@@ -213,7 +119,7 @@ import { parsePullUrl } from "../lib/github.js";
 
 export type Complexity = "trivial" | "moderate" | "large";
 
-/** Deterministic policy: the tool rates the change, not the model. */
+/** Rate complexity from fixed line and file-count thresholds. */
 function rateComplexity(linesChanged: number, changedFiles: number): Complexity {
   if (linesChanged <= 25 && changedFiles <= 2) {
     return "trivial";
@@ -280,58 +186,30 @@ export default defineTool({
 });
 ```
 
-The file adds one tool named `inspect_pr`:
-
-- `description` tells the model when to call it.
-- `inputSchema` defines and validates the arguments.
-- `execute` runs on the server and returns data to the model.
+## Verify complexity classification
 
-Two details carry the design. `rateComplexity` is the review policy,
-and it lives in code: the model never decides what counts as a big
-change. And `ctx.host.github` is the shared host GitHub client, so the
-tool inherits whatever credential the host has (a token, `gh auth`, or
-a GitHub App) without parsing any of it.
-
-## Try the inspect tool
-
-Call the tool directly first, on a real merged pull request:
+Run `inspect_pr` against a small pull request:
 
 ```bash
 agent-sdk call inspect_pr --dir . \
   --input '{"prUrl":"https://github.com/facebook/react/pull/35623"}'
 ```
 
-`call` validates the input and runs `execute` without a model turn.
-This PR is a one-character typo fix, so the result comes back rated
-`trivial` with the whole patch inline:
-
-```json
-{
-  "title": "Fix typo: accomodate -> accommodate",
-  "additions": 1,
-  "deletions": 1,
-  "changedFiles": 1,
-  "complexity": "trivial",
-  "files": [{ "path": "compiler/packages/...", "patch": "@@ -1315,7 ..." }]
-}
-```
+Confirm the result contains `"complexity": "trivial"`.
 
-Now call it on the PR that added `experimental_useEvent` to React:
-1,027 additions across 26 files.
+Run it against a large pull request:
 
 ```bash
 agent-sdk call inspect_pr --dir . \
   --input '{"prUrl":"https://github.com/facebook/react/pull/25229"}'
 ```
 
-The rating flips to `large` and the patches disappear from the result.
-The policy in the tool decides how much the model gets to see, before
-any model turn spends a token on it.
+Confirm the result contains `"complexity": "large"` and no `patch`
+fields.
 
 ## Add the review tool
 
-The approver needs a way to act on its verdict. Create
-`agent/tools/submit_review.ts`:
+Create `agent/tools/submit_review.ts` to post each verdict:
 
 ```ts
 import { defineTool } from "@cursor/july/tools";
@@ -354,10 +232,10 @@ export default defineTool({
     const { owner, repo, number } = parsePullUrl(prUrl);
     const review =
       verdict === "approve"
-        ? { event: "APPROVE" as const, body: `PR approver: ${summary}` }
+        ? { event: "APPROVE" as const, body: `PR reviewer: ${summary}` }
         : {
             event: "COMMENT" as const,
-            body: `PR approver: this change needs a human review. ${summary}`,
+            body: `PR reviewer: this change needs a human review. ${summary}`,
           };
 
     const octokit = await ctx.host.github.getOctokit();
@@ -373,47 +251,24 @@ export default defineTool({
 });
 ```
 
-The tool posts a real review: an APPROVE when the agent approves, a
-comment asking for a human otherwise. Two GitHub rules shape how you
-test it. Your credential needs write access to the repo it reviews,
-and GitHub rejects approving your own pull request, so hand the agent
-a teammate's PR rather than one you authored. When a post fails, the
-tool call reports the GitHub error to the model and the turn keeps
-going.
-
-Want a person to sign off before the review lands? Set
-`needsApproval: true` on the tool and the call parks until someone
-approves it from the playground or Slack.
-[Human-in-the-loop approvals](./guides/human-in-the-loop.md) shows the
-flow.
+Use a GitHub credential with write access and a pull request you didn't
+author.
 
 ## Review a pull request
 
-Run the whole loop on a pull request your credential can review. A
-teammate's open PR is the right pick: write access to the repo, and
-not authored by you.
+Review an open pull request:
 
 ```bash
 agent-sdk run --dir . \
   --message "Review https://github.com/acme/checkout/pull/42"
 ```
 
-The trajectory shows two tool calls. The agent inspects the PR, reads
-the patches, and submits its verdict. A small, clean change gets an
-APPROVE review on the spot, with a one-line summary of what it checked.
-A large one gets a comment asking for a human review, pointing at the
-files a reviewer should start with. Same instructions, different
-behavior, because the policy in the tool decided how much the model got
-to see.
-
-Open the PR on GitHub: the review is on the timeline, posted by
-whatever identity your credential belongs to.
+Confirm `inspect_pr` runs before `submit_review`, then verify the review
+on GitHub.
 
-## Wake it from GitHub
+## Trigger reviews from GitHub
 
-A reviewer you have to prompt is only half useful. Give the agent a
-GitHub channel so pull requests wake it. Create
-`agent/channels/github.ts`:
+Create `agent/channels/github.ts`:
 
 ```ts
 import {
@@ -424,10 +279,8 @@ import {
 const REVIEW_ACTIONS = new Set(["opened", "reopened", "ready_for_review"]);
 
 export default githubChannel({
-  botName: "pr-approver",
+  botName: "sdk-pr-reviewer",
   webhookEvents: ["pull_request"],
-  // submit_review owns every GitHub write. Without these flags the channel
-  // also posts chat replies and reactions to the PR when the token allows it.
   deliverReplies: false,
   progress: { reactions: false },
   onPullRequest: (ctx, pr) => {
@@ -446,57 +299,66 @@ export default githubChannel({
 });
 ```
 
-The channel mounts `POST /v1/channels/github` and dispatches on the
-`pull_request` events you declared. Opened, reopened, and undrafted PRs
-start a model turn; everything else returns `null` and is skipped.
-
-Serve the agent, then replay a real PR at it from a second terminal.
-`replay` reads the PR through `gh api`, synthesizes a GitHub-shaped
-webhook delivery, and POSTs it to the channel. No repo admin, no
-tunnel:
+Keep `agent-sdk dev` running. In a second terminal, replay an open pull
+request. Pull access is enough; repo admin isn't required:
 
 ```bash
-agent-sdk dev
-# second terminal:
 agent-sdk github replay https://github.com/acme/checkout/pull/42 \
   --dir . --action opened
 ```
 
-The replay prints the delivery, and the serve terminal shows the wake:
+Open the playground and confirm `Review acme/checkout#42` contains the
+trigger, both tool calls, and the verdict.
 
-```text
-[agent-sdk] replaying acme/checkout#42 (pull_request) → 1 channel
-[agent-sdk]   pull_request.opened → pr-approver/github 200
-```
+## Run options
+
+1. **CLI message**
+
+   ```bash
+   agent-sdk run --dir . --message "Review https://github.com/acme/checkout/pull/42"
+   ```
+
+2. **Local replay**
+
+   ```bash
+   agent-sdk github replay https://github.com/acme/checkout/pull/42 \
+     --dir . --action opened
+   ```
+
+3. **Forward or `--cursor-events`**
+
+   Pull Cursor events:
+
+   ```bash
+   agent-sdk serve --dir . --cursor-events --repo owner/repo
+   ```
+
+   Forward GitHub webhooks:
+
+   ```bash
+   agent-sdk github forward --dir .
+   ```
 
-The agent runs the same inspect-then-submit loop, unprompted this time.
-Replay the same PR again and the channel resumes that PR's session
-instead of starting a new one: each pull request keeps one running
-conversation.
+   Keep the local `dev` or `serve` process running.
 
-## Open the playground
+4. **Hosted deployment**
 
-Keep `agent-sdk dev` running and open the playground URL it printed. The
-webhook session is in the session list, titled
-`Review acme/checkout#42`, with the trigger message, both tool calls,
-and the verdict laid out. Start a new chat there and ask for another
-review to watch a turn stream live.
+   Deploy once, set the GitHub App secrets, then redeploy:
 
-## Go live
+   ```bash
+   agent-sdk deploy
+   agent-sdk secrets set sdk-pr-reviewer GITHUB_APP_ID GITHUB_APP_PRIVATE_KEY
+   agent-sdk deploy
+   ```
 
-Replay is for development. For real deliveries, serve with
-`--cursor-events --repo owner/repo` to pull events for repositories
-connected to Cursor with no public URL, or run
-`agent-sdk github forward` to relay webhooks to your dev server. The
-[GitHub guide](./guides/github.md) compares the options. In production,
-give the host GitHub App credentials so reviews post as your app's bot
-identity instead of a personal account.
+See [GitHub](./guides/github.md) for local event delivery and
+[Deployment](./deployment.md) for hosting.
 
 ## Where to go next
 
-- [`examples/approval-buddy`](../examples/approval-buddy/): the
-  production-shaped sibling, with commit statuses, review subagents,
-  and a deterministic stamp policy
+- [`examples/approval-buddy`](../examples/approval-buddy/): an example
+  with commit statuses, review subagents, and a deterministic stamp
+  policy
 - [Evals](./evals.md): freeze these two PRs as regression checks so
   prompt changes can't flip a verdict
 - [Tools](./reference/tools.md): more on typed tools, approvals, and

package/docs/reference/agent-config.md

@@ -44,6 +44,7 @@ export default defineAgent({
 | `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). |
 | `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). |
 
 ## Choose a model
 
@@ -120,6 +121,52 @@ outside it (or runs with `--state-root` under `/tmp`). An agent that
 *needs* a specific checkout's skills and rules points `cwd` inside that
 checkout.
 
+## Allowlist built-in 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.
+
+```ts
+export default defineAgent({
+  model: "composer-2.5",
+  // Read-only triage agent: search and read only.
+  // No shell, no edits, no subagents.
+  tools: ["read", "grep", "glob", "ls"],
+});
+```
+
+Agent Serve 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.
+
+Use the SDK's public tool names, including `"shell"`, `"read"`,
+`"edit"`, `"grep"`, `"glob"`, `"ls"`, and `"task"`. Unknown names
+fail the turn with a `ConfigurationError`.
+
+Two names have broader effects:
+
+- `"shell"` also grants shell input. Tools with
+  `execution: "agent"` need it to run their scripts. Discovery warns
+  when your allowlist would prevent those tools from running.
+- `"task"` lets the root agent start subagents. Each subagent keeps
+  its own curated toolset.
+
+Tool allowlists work only with the local runtime. A
+`runtime: "cloud"` agent that sets `tools` fails at serve startup.
+Agent Serve also refuses per-send cloud sessions from a hybrid agent
+with an allowlist. It won't run those sessions with unrestricted tool
+access.
+
+The allowlist controls which tools the model can call. It does not
+isolate the serve host. For agents that process untrusted input, also
+set `local: { sandbox: true }`.
+
 ## The `cloud` block
 
 Cloud agent defaults forwarded to the Cursor SDK: `repos` (each

package/docs/reference/cli.md

@@ -141,8 +141,8 @@ agent folder as a positional path, or run it from inside the project:
 
 ```bash
 agent-sdk dev
-agent-sdk dev ./pr-approver
-agent-sdk dev ./pr-approver --port 3000
+agent-sdk dev ./sdk-pr-reviewer
+agent-sdk dev ./sdk-pr-reviewer --port 3000
 ```
 
 `dev` accepts the same flags as [`serve`](#serve). You can use `--dir`

package/docs/reference/hooks.md

@@ -67,7 +67,7 @@ All of them consume the same stream, for different jobs:
 | Can affect the run | no | yes, it owns the surface | n/a | yes through arm instructions or `session.abs`; collection is observe-only |
 | Authored at | `agent/hooks/*.ts` | channel config | `evals/**/*.eval.ts` | [`agent/ab.ts` or `agent/ab/*.ts`](../ab.md) |
 
-For GitHub commit status and sticky PR banners, use
+For GitHub merge-box checks and sticky PR banners, use
 `githubChannel({ progress: { commitStatus, banner } })` from
 `@cursor/july/channels/github`. That is the supported Autofix-style
 path. See [GitHub: Show PR progress](../guides/github.md#show-pr-progress).

package/docs/reference/tools.md

@@ -82,10 +82,11 @@ export default defineTool({
 `ctx.host` carries the shared host services: `host.mcp` (authored MCP
 connections: `names()`, `listTools(name)`, `callTool(name, tool, args)`),
 `host.github` and `host.slack` (shared platform clients), `host.kv` and
-`host.files` (durable [storage](../storage.md)), `host.reminders`
-(per-session wakes, when attached), `host.evals` (playground eval
-batches, when attached), and `host.slackNudges` (Slack ask-dedupe
-helpers).
+`host.files` (durable [storage](../storage.md)), `host.otel` (custom
+metrics and session tags; see [OpenTelemetry](../guides/opentelemetry.md)),
+`host.reminders` (per-session wakes, when attached), `host.evals`
+(playground eval batches, when attached), and `host.slackNudges`
+(Slack ask-dedupe helpers).
 
 ### Return values