@cursor/july 0.1.95 → 0.1.97

package/docs/guides/slack.md

@@ -1,20 +1,18 @@
 ---
 title: "Slack"
-description: "Put the agent in Slack: a dedicated Socket Mode app via the dashboard wizard, or a manual manifest import."
+description: "Run a Socket Mode Slack bot from the dashboard wizard, or import an app you own."
 ---
 
 # Slack agents
 
-The Slack channel puts your agent in Slack as its own Socket Mode bot.
-`agent-sdk slack create` opens the dashboard wizard and writes tokens
-to `.env.local`. To own the Slack app yourself, run
-`agent-sdk slack init --manual` and paste the manifests at
-[api.slack.com](https://api.slack.com/apps). Socket Mode has no
-public Request URL. Replies stream in threads, with tool "thinking" steps,
-suggested prompts, and opt-in approval buttons.
+The Slack channel is a Socket Mode bot. The app connects out, so you
+don't need a public Request URL. Mentions and DMs start a thread.
+Replies stream there, with thinking steps and suggested prompts.
 
-The companion skill is
-[`skills/setup-slack/SKILL.md`](../../skills/setup-slack/SKILL.md).
+Use `agent-sdk slack create` when Cursor should own the Slack app. Use
+`agent-sdk slack init --manual` when you own it. Commands and flags live
+in the [CLI reference](../reference/cli.md#slack). Coding agents should
+follow [`skills/setup-slack/SKILL.md`](../../skills/setup-slack/SKILL.md).
 
 ## Define the channel
 
@@ -24,35 +22,23 @@ Author `agent/channels/slack.ts` with `slackChannel()` from
 ```ts
 import { slackChannel } from "@cursor/july/channels/slack";
 
-// Single agent: reads SLACK_BOT_TOKEN + SLACK_APP_TOKEN
 export default slackChannel();
-
-// Multi-agent serve: one Slack app (and token pair) per agent
-export default slackChannel({ envPrefix: "WEATHER_AGENT" });
-// → WEATHER_AGENT_SLACK_BOT_TOKEN + WEATHER_AGENT_SLACK_APP_TOKEN
 ```
 
-By default the channel connects over Socket Mode (the app connects
-outward, so it works from behind any firewall) and responds only to
-`app_mention` events and direct messages. It also refuses Slack Connect
-users, guests, and senders from other workspaces. Threads bind to
-sessions with `continuationToken = channelId:threadTs`, so a thread is
-one durable conversation. Replies stream (`chat.startStream` /
-`appendStream` / `stopStream`) with a plain-message fallback, a rotating
-status shows while the agent works, and the pack sets thread titles and
-suggested prompts. When a Slack API is unavailable (`method_not_found`,
-`missing_scope`), the pack degrades to `postMessage` instead of failing.
-
-Missing tokens leave the channel idle (`channel idle … missing
-credentials`) rather than failing `serve`. That's useful when you mount
-many agents and only some have Slack apps.
+`slackChannel()` reads `SLACK_BOT_TOKEN` and `SLACK_APP_TOKEN`. Pass
+`envPrefix: "WEATHER_AGENT"` to read `WEATHER_AGENT_SLACK_BOT_TOKEN`
+and `WEATHER_AGENT_SLACK_APP_TOKEN` instead. Use a prefix when one
+host serves several Slack bots.
+
+A thread is one conversation. The bot answers mentions and DMs. It
+refuses Slack Connect users, guests, and people from other workspaces.
+Missing tokens leave this channel idle. The rest of `serve` still
+starts.
 
 ## Control who can message the agent
 
-External senders are blocked by default. Slack Connect users, guests, and
-people whose home workspace is not the install team never reach the
-handler. Set `blockExternals: false` only when the agent should serve
-people outside your org:
+External senders are blocked. Set `blockExternals: false` only when
+people outside your org should reach the agent:
 
 ```ts
 export default slackChannel({
@@ -60,9 +46,8 @@ export default slackChannel({
 });
 ```
 
-Sessions are thread-scoped by default, so anyone in the thread can
-continue. Restrict follow-ups to the person who started the session with
-`respondTo: "author"`:
+Anyone in the thread can continue it. Restrict follow-ups to the person
+who started the session with `respondTo: "author"`:
 
 ```ts
 export default slackChannel({
@@ -72,234 +57,140 @@ export default slackChannel({
 
 ## Set it up
 
-For a dedicated Socket Mode bot, run `agent-sdk slack create`. The CLI
-opens the signed-in Cursor dashboard wizard. Slack consent, bot name,
-and admin-approval wait happen there. Tokens are stored as deployment
-secrets and written to `.env.local`. They are never shown. Do not paste
-a manifest at [api.slack.com](https://api.slack.com/apps) unless you
-are on the [manual setup](#manual-setup) path.
-
-Bots that already have tokens in `.env.local` keep working. Skip the
-wizard unless you want a Cursor-managed app.
+`slack create` opens the Cursor dashboard wizard. Finish Slack consent
+and the bot name there. The CLI writes tokens to `.env.local` and never
+prints them. Skip the wizard if those tokens are already set, unless
+you want a Cursor-managed app.
 
 ### Provision with the CLI
 
 ```bash
-agent-sdk slack create --dir .          # dev app (default)
-agent-sdk slack create --dir . --prod   # prod app
+agent-sdk slack create --dir .
+agent-sdk slack create --dir . --prod
 ```
 
-`slack create` needs a signed-in host (`agent-sdk login` or
-`CURSOR_API_KEY`). It scaffolds `agent/channels/slack.ts` when the file
-is missing, opens the dashboard wizard, and waits. Finish **Add Slack
-to this agent** in the browser as the same Cursor account. The CLI
-writes `<PREFIX>_SLACK_BOT_TOKEN` and `<PREFIX>_SLACK_APP_TOKEN` into
-`<dir>/.env.local`, then runs `doctor`. Serve and smoke it as described
-[below](#wire-the-env-and-verify).
-
-If Slack needs a workspace admin to approve the app, keep the CLI
-running. Managed install does not file the request. Open Slack's
-**Request approval** page (the CLI prints the link; the same URL is
-**Send a reminder** after you submit). After an admin approves, click
+Sign in first (`agent-sdk login` or `CURSOR_API_KEY`). Finish **Add
+Slack to this agent** as the same Cursor account. Then run
+`agent-sdk slack doctor --prefix MY_AGENT` and serve:
+
+```bash
+agent-sdk serve --dir . --dev
+```
+
+Invite the bot and mention it, or DM it. Expect a Thinking status,
+then a threaded streaming reply.
+
+If Slack needs a workspace admin, keep the CLI running. Open the
+**Request approval** link it prints. After an admin approves, click
 **Retry** in the wizard.
 
-Useful companions: `--name` / `--icon` / `--channel-posts` prefill the
-wizard. `--slack-team T0123ABCD` picks a workspace when several are
-connected. A second `slack create` for the same agent and env overwrites
-that Slack app. It keeps the Slack app id and replaces the manifest and
-tokens. `agent-sdk slack destroy` deletes the provisioned app.
-`agent-sdk slack icon <source>` updates the icon later.
+`slack destroy` deletes the Cursor-managed app. `slack icon` updates
+its icon. A second `slack create` for the same agent and environment
+replaces that app's manifest and tokens.
 
 ### Provision from the dashboard
 
 The same wizard is on [Deployed Agents](https://cursor.com/dashboard).
-Open **Integrations** on an agent and click **Add Slack to this agent**,
-or follow the URL `slack create` printed.
+Open **Integrations** and click **Add Slack to this agent**.
 
-A first-run agent that has no hosted engine yet shows **Not deployed
-yet**. Local `agent-sdk serve` works from `.env.local`. The next
-**Deploy** injects the stored secrets; there is no Slack-only Redeploy.
+Local `agent-sdk serve` reads `.env.local`. The next deploy injects the
+stored secrets.
 
-If Slack needs admin approval, the wizard waits. Click **Request
-approval** to file the request in Slack (that same page later sends a
-reminder). After an admin approves, click **Retry**.
+If Slack needs admin approval, click **Request approval**, then
+**Retry** after an admin approves.
 
-The app row's menu covers later care: rename, set an icon, rotate
-tokens, remove the app, or disconnect the workspace.
+The app row's menu covers rename, icon, token rotation, removal, and
+workspace disconnect.
 
-### Wire the env and verify
+### Create your own Slack app
 
-`agent-sdk slack create` already wrote the tokens to `.env.local`, so
-after provisioning skip straight to `doctor`. `serve` / `dev` /
-`slack doctor` load that file (real environment variables always win).
+`slack init --manual` is for an app you own. It writes the channel file
+and Slack manifests. When Slack CLI (`~/.slack/bin/slack`) is logged
+in, it installs the app. When it isn't, install the app yourself.
 
 ```bash
-agent-sdk slack doctor --prefix MY_AGENT
-```
-
-Proceed when `app_token`, `connections_open`, `bot_token`, and
-`auth_test` are all green. Then serve and smoke it:
-
-```bash
-agent-sdk serve --dir . --dev
-# expect: [agent-sdk/slack] Socket Mode connected
+agent-sdk slack init --manual --dir . --name "My Agent"
 ```
 
-Invite the bot to a channel and @mention it (or DM it). Expect the
-Thinking… status, then a threaded streaming reply, with correlated
-server logs (`inbound kind=app_mention`, `session start`,
-`reply delivered via stream|postMessage`).
-
-### Manual setup
-
-`slack init --manual` is for a Slack app you own at api.slack.com. You
-paste the generated manifests and mint tokens yourself. Use this when
-you want an unmanaged app, or when the dashboard wizard is not an
-option.
+Install Slack CLI if you need it:
 
 ```bash
-agent-sdk slack init --manual --dir . --name "My Agent"
+curl -fsSL https://downloads.slack-edge.com/slack-cli/install.sh | bash
 ```
 
-That writes `agent/channels/slack.ts`, Slack manifests under the
-project state directory, `env.example`, and `setup-status.json`.
-`--no-prefix` uses shared `SLACK_*` variables on
-a single-agent host. `--prefix CUSTOM` overrides the directory-derived
-prefix. `--channel-posts` subscribes the manifests to channel-post
-events.
+Log in with `slack login --no-prompt`. In Slack, send
+`/slackauthticket <ticket>`, then
+`slack login --ticket <ticket> --challenge <code>`. Install the
+workspace app with `slack app install`. Create a separate production
+app the same way.
 
-`slack manifest --env both` regenerates the JSON files without
-touching the channel file.
+Or paste `.slack/manifest.dev.json` at
+[api.slack.com/apps](https://api.slack.com/apps) (**Create New App** →
+**From a manifest**). Repeat with `.slack/manifest.prod.json`. Dev and
+prod are separate Slack apps.
 
-#### Create the apps
+Then put a bot token (`xoxb-...`) and an app-level token with
+`connections:write` (`xapp-...`) in `.env.local`. Use the names
+`slack init --manual` printed. Run `slack doctor` and serve as above.
 
-This phase needs someone with permission to create Slack apps.
-
-1. Open [api.slack.com/apps](https://api.slack.com/apps) → **Create New
-   App** → **From a manifest**.
-2. Paste `manifest.dev.json` and create the dev app.
-3. Repeat with `manifest.prod.json`. Dev and prod are separate Slack
-   apps with separate tokens.
-
-#### Install and mint tokens
-
-For each app: **Install to Workspace** and copy the Bot User OAuth Token
-(`xoxb-…`). Then under **Basic Information → App-Level Tokens** create a
-token with scope `connections:write` and copy it (`xapp-…`).
-
-Put the pair in `.env.local` using the names from `env.example`, then
-run `slack doctor` and serve as [above](#wire-the-env-and-verify).
+Serve this app with Agent SDK. Do not run `slack deploy`.
 
 ## Choose when the agent engages
 
-Mentions and DMs are on by default. Watching channels means dispatching
-on new posts without a mention. That's an explicit opt-in:
+Mentions and DMs are on. Watching channel posts without a mention is
+opt-in:
 
 ```ts
 export default slackChannel({
   envPrefix: "TRIAGE",
   engagement: {
-    // mentions / directMessages default to true
     channelPosts: {
-      allow: ["#triage-alerts"], // use ["*"] for every joined channel
-      posts: "top-level",       // default: thread replies never dispatch
-      debounceMs: 15_000,       // optional: let rapid edits settle
-      includeBotPosts: false,   // default: bot-authored posts never dispatch
+      allow: ["#triage-alerts"],
+      posts: "top-level",
+      debounceMs: 15_000,
     },
   },
-  onChannelPost: async (ctx, message) => {
-    // same contract as onAppMention: return null to skip
+  onChannelPost: async (_ctx, message) => {
     return message.markdown.length > 20 ? {} : null;
   },
 });
 ```
 
-Channel watching needs the `message.channels` / `message.groups` events
-on the Slack app. Pass `--channel-posts` on `slack create` or
-`slack init --manual`. The bot must also be a member of each watched
-channel.
-
-Set `allow: ["*"]` to watch every channel the bot has joined.
+Pass `--channel-posts` on `slack create` or `slack init --manual` so
+the Slack app receives those events. The bot must be in each watched
+channel. `allow: ["*"]` watches every joined channel.
 
-Set `includeBotPosts: true` when the posts worth watching come from bots:
-alert feeds, webhook integrations, or other agents posting notes. The
-watching app's own posts stay dropped either way, matched by the `bot_id`
-and bot user id from `auth.test`, so an agent can never dispatch on its
-own replies. Use this for a bot-fed alerts channel.
+Set `includeBotPosts: true` for alert feeds and other bots. This app
+never wakes on its own posts.
 
 ## Prepare work on the host
 
 Mention and DM handlers may return a prepared `message`,
-`workspaceFiles`, or `cloud` block. It's the same host-prep pattern as
+`workspaceFiles`, or `cloud` block. Use the same host-prep pattern as
 [custom channels](./webhooks.md#prepare-on-the-host-then-hand-off).
-PR agents use it: extract a PR URL from the mention text and run the
-same host path as the HTTP channel.
 
-Slack file uploads are attached automatically. Images become vision input.
+Slack file uploads attach automatically. Images become vision input.
 Supported documents become workspace files for the turn.
 
 ## Add approval buttons
 
-Tools with `needsApproval` park until a person decides. Route that
-through Slack with one flag:
+Tools with `needsApproval` park until a person decides. Post those
+decisions in Slack with one flag:
 
 ```ts
 export default slackChannel({
-  toolApprovals: true, // posts Block Kit Approve/Deny cards + routes clicks
+  toolApprovals: true,
 });
 ```
 
-Approval cards need interactivity on the Slack app. Recreate with
-`slack create` if clicks do nothing. Composing events by hand: spread
-`buildToolApprovalEvents({ credentials })` into `events` and set
-`interactivity: true` on the channel so Socket Mode routes the clicks.
-
-Cards show redacted, truncated arguments (Block Kit size limits);
-execution still uses the full validated input, so review sensitive tools
-in the playground when the arguments may exceed the card. Approvals
-exist for `execution: "server"` tools on the local runtime only, and
-parked calls do not survive a host restart. The full lifecycle is in
+The Slack app needs interactivity. Recreate it with `slack create` if
+clicks do nothing. Cards show redacted, truncated arguments. Execution
+still uses the full input, so review sensitive tools in the playground
+when the card may hide fields. The lifecycle is in
 [Human-in-the-loop](./human-in-the-loop.md).
 
 ## Run several agents on one host
 
-One Slack app and token pair per agent. Never share a pair across
-agents in the same process. `envPrefix` keeps them apart
-(`WEATHER_AGENT_SLACK_*`, `TRIAGE_SLACK_*`, …), and agents without tokens mount
-with their Slack channel idle while everything else serves normally.
-
-## Keep the channel healthy
-
-Two habits matter most.
-
-- Don't `await` long work inside Slack dispatch handlers. The pack
-  dispatches through `waitUntil` and streams as the turn progresses.
-- In `--dev` (loopback) or `--allow-anonymous` (trusted shared host), the
-  playground can list and stream Slack sessions and resolve their parked
-  approvals (the audit trail records the HTTP caller). Bearer-auth hosts
-  stay strict: Slack approvals must come from Slack interactivity or a
-  matching principal.
-
-## CLI reference
-
-The `slack` subcommands cover setup end to end.
-
-```bash
-agent-sdk slack setup                     # printed setup guide
-agent-sdk slack create --dir .            # dashboard wizard (dev app)
-agent-sdk slack create --dir . --prod     # prod app
-agent-sdk slack destroy --dir .           # delete the provisioned app
-agent-sdk slack icon ./icon.png --dir .   # set the provisioned app's icon
-agent-sdk slack init --manual --dir .     # manifests to paste at api.slack.com
-agent-sdk slack manifest --env both       # regenerate those JSON files
-agent-sdk slack doctor --prefix MY_AGENT  # token / connectivity checks
-```
-
-## What's next
-
-Continue with these pages:
-
-- [Human-in-the-loop](./human-in-the-loop.md): the approval lifecycle
-  behind `toolApprovals`
-- [Webhooks and custom channels](./webhooks.md): the mechanism this
-  pack is built on
+Give each agent its own Slack app and token pair. Set `envPrefix` so
+the names don't collide (`WEATHER_AGENT_SLACK_*`, `TRIAGE_SLACK_*`).
+Agents without tokens stay idle. The others still serve.

package/docs/reference/agent-config.md

@@ -184,8 +184,8 @@ When every slot is busy, newly admitted turns queue FIFO instead of
 failing: the stream records a durable `turn.queued` event with the
 queue position, `GET /v1/sessions` reports `queued: true`, and each
 queued turn starts as soon as a slot frees. A queued turn still counts
-as running for busy semantics: follow-ups preempt it, and direct tool
-calls get `409 session_busy`. Omit for unlimited.
+as running for busy semantics: follow-ups preempt it, and direct
+write-effect tool calls get `409 session_busy`. Omit for unlimited.
 
 ```ts
 export default defineAgent({

package/docs/reference/cli.md

@@ -342,8 +342,9 @@ the value before execution. A local call needs no inference credential.
 A hosted call still needs Cursor credentials to reach the deployment.
 
 `--session` runs the tool inside an existing session and records it on
-the event stream. If a model turn is active or pending, the server
-returns `session_busy`; retry after the turn finishes. The command
+the event stream. If a model turn is active or pending, a read-effect
+tool runs alongside it and a write-effect tool gets `session_busy`;
+retry after the turn finishes. The command
 prints the server's JSON response and exits non-zero unless the HTTP
 response succeeds with `ok: true`. See
 [Tools](./tools.md#call-a-tool-without-a-model-turn).
@@ -414,6 +415,8 @@ non-zero when the reconstructed trajectory failed.
 ```bash
 agent-sdk init ./my-agent          # scaffold package.json, tsconfig.json, agent/ + a demo tool
 agent-sdk init ./my-demo --template demo              # record a PR walkthrough
+agent-sdk init ./code-wiki --template code-wiki       # keep wiki pages current after merge
+agent-sdk init ./agents-md --template agents-md       # keep AGENTS.md current from last week's PRs and Slack
 agent-sdk init ./my-reviewer --template security-reviewer   # review PRs for security bugs
 agent-sdk init ./security-help --template security-help   # answer security questions in Slack
 agent-sdk init ./my-triage --template triage-linear   # comment on Linear issues
@@ -431,8 +434,9 @@ agent-sdk init                     # no directory: print the setup guide
 `@cursor/july` resolves for `dev` and `run`.
 
 Templates may ship `init.json`. On a TTY, `init` asks those questions
-before writing files. `pr-autofixer` and `security-help` ask for GitHub
-repos. Repeat
+before writing files. `code-wiki`, `pr-autofixer`, `security-help`, and
+`agents-md` ask for GitHub repos. `agents-md` also asks for Slack
+channels. Repeat
 `--var id=value` to answer without a prompt.
 `--json` and non-TTY hosts skip the interview unless `--var` is set.
 
@@ -590,7 +594,8 @@ commands with an explicit `--json` flag skip this automatic check.
 agent-sdk deploy [--dir <path>] [--slug <slug> | --all] [--team <id>]
                 [--repo <https-url>] [--ref <git-ref>] [--path <agent-path>]
                 [--cursor-events-repo owner/name]...
-                [--allow-domain <domain>]... [--no-wait] [--json]
+                [--allow-domain <domain>]... [--multi-tenant]
+                [--no-wait] [--json]
 ```
 
 Managed hosting requires team-admin permission and the team's
@@ -617,6 +622,12 @@ be a lowercase hostname with at least two labels and an alphabetic
 top-level domain. One leading `*.` wildcard is allowed. A deployment
 can declare at most 20 domains.
 
+`--multi-tenant` adds a release to an existing Cursor-managed
+(multi-tenant) product such as `security-reviewer`. It is valid only
+for `architecture: "v2"` and cannot create a new multi-tenant
+application — those stay on the operator seed path. Without the flag,
+HTTP deploy stays single-tenant and a managed slug 409s.
+
 By default, the command polls every three seconds for up to ten minutes
 and succeeds only when the deployment reaches `running`. `--no-wait`
 returns after the deployment request is accepted. Multi-agent deploys
@@ -743,6 +754,8 @@ URL connections run a browser PKCE flow. Tokens are written to
 `mcp-auth.json` under the CLI config directory (override with
 `AGENT_SERVE_CONFIG_DIR`). Pass `--store` to upsert matching
 `MCP_OAUTH_<CONNECTION>_*` secrets on the hosted deployment.
+`--store` is the path for the next deploy. Hosted Connect lets the
+current process retry.
 
 Cursor-account connections authorize the hosted deployment's service
 account through the Cursor backend's connector consent flow. Those
@@ -821,6 +834,7 @@ agent-sdk slack icon <https-url-or-file> [--dir <path>] [--prod]
                     [--slack-team <T…>] [--team <id>] [--json]
 agent-sdk slack init --manual [--dir <path>] [--name <name>]
                     [--prefix <prefix> | --no-prefix] [--channel-posts]
+                    [--install | --no-install] [--slack-team <T…>] [--prod]
 agent-sdk slack manifest [--dir <path>] [--name <name>]
                     [--env dev|prod|both] [--channel-posts] [--print]
 agent-sdk slack doctor [--dir <path>] [--prefix <prefix> | --no-prefix] [--json]
@@ -849,17 +863,26 @@ a local png, jpg, or gif file of at most 512KB.
 
 `slack init` without `--manual` exits non-zero and writes no files. Use
 `slack create` for the dashboard wizard. `slack init --manual` writes
-the channel file, development and production manifests, `env.example`,
-and setup status under the project. You paste those manifests at
-api.slack.com. The command refuses to overwrite a target file. If a
-collision occurs, it exits non-zero; files created earlier in the run
-remain. The token prefix defaults to the directory basename normalized
-to uppercase snake case. Explicit `--prefix` values use the same
-normalization. For example, `pr-approver` becomes
-`PR_APPROVER_SLACK_BOT_TOKEN`. `--no-prefix` uses shared
-`SLACK_BOT_TOKEN` and `SLACK_APP_TOKEN`. `--channel-posts` subscribes
-the manifests to channel-post events. The command always prints a JSON
-summary.
+the channel file, development and production manifests, a Slack CLI
+`.slack/` project (hook + manifests, committed with the repo). When
+Slack CLI is logged in, it installs the app. Otherwise `next` asks
+you to install it. `--install` requires that install. `--no-install`
+skips it. `--prod` selects the deployed app.
+`--slack-team` picks the workspace. Slack CLI keeps install tokens in
+that process; copy `xoxb` and mint `xapp` (`connections:write`) into
+`.env.local`. Tokens that appear in `.env` during that install are
+copied onto the prefixed names. Paste `.slack/manifest.dev.json` at
+api.slack.com when the Slack CLI is missing. Do not run
+`slack deploy`. The command refuses to overwrite the channel file.
+It updates the Slack CLI hook and manifests when `.slack/` already
+exists. If a collision occurs, it exits non-zero; files created
+earlier in the run remain. The token prefix defaults to the directory
+basename normalized to uppercase snake case.
+Explicit `--prefix` values use the same normalization. For example,
+`pr-approver` becomes `PR_APPROVER_SLACK_BOT_TOKEN`. `--no-prefix`
+uses shared `SLACK_BOT_TOKEN` and `SLACK_APP_TOKEN`.
+`--channel-posts` subscribes the manifests to channel-post events.
+The command always prints a JSON summary.
 
 `slack manifest` regenerates selected manifest files. `--env` defaults
 to `both`, and `--name` defaults to the directory name. `--print` writes

package/docs/reference/connections.md

@@ -35,8 +35,10 @@ Tokens come from env vars. Never hardcode them in the file.
 ## Host MCP OAuth
 
 For servers that speak OAuth, set `oauth: true` and authorize with the
-CLI. Tokens live in `mcp-auth.json` under the CLI config directory. `--store`
-copies them onto the hosted deployment as `MCP_OAUTH_<NAME>_*` secrets.
+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.
 
 ```ts
 export default defineConnection({
@@ -48,6 +50,7 @@ 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](../guides/mcp-oauth.md). Companion
@@ -266,7 +269,7 @@ lazily on first use.
 
 Continue with these pages:
 
-- [Host MCP OAuth](../guides/mcp-oauth.md): `mcp oauth`, `--store`
+- [Host MCP OAuth](../guides/mcp-oauth.md): `mcp oauth`, Connect, `--store`
 - [Agent-to-agent](../guides/agent-to-agent.md): peers in depth
 - [Tools](./tools.md): authored tools that wrap MCP connections
 - [Webhooks](../guides/webhooks.md): calling MCP connections from handlers

package/docs/reference/http-api.md

@@ -134,7 +134,8 @@ curl -X POST http://127.0.0.1:3000/<slug>/v1/tools/inspect_pr \
 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`
-while a turn runs). Agent-execution tools are rejected with `400`, and
+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](./tools.md#call-a-tool-without-a-model-turn).
 

package/docs/reference/sessions.md

@@ -67,8 +67,10 @@ message. Interrupted turns record `turn.failed` with
 Slack `stop` / `@agent stop` does the same for that thread and clears
 pending coalesced nudges.
 
-Session-bound deterministic tool calls share the same execution lock.
-They return `409 session_busy` while a model turn is running.
+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](./tools.md#call-a-tool-without-a-model-turn)).
 
 ## Which events can I stream?
 

package/docs/reference/tools.md

@@ -263,7 +263,14 @@ 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.
-Session-bound calls return `409 session_busy` while a turn runs. When the
+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
@@ -273,7 +280,7 @@ 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 `409 session_busy`, same event recording. A token with no
+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