@mastra/mcp-docs-server 1.1.46-alpha.3 → 1.1.46-alpha.4

package/.docs/reference/ai-sdk/to-ai-sdk-stream.md

@@ -19,7 +19,7 @@ When the source agent stream includes a final structured output object, `toAISdk
 }
 ```
 
-The `object` field contains your full structured output value. This maps Mastra's final structured output chunk into the AI SDK UI stream. Partial structured output chunks are not emitted.
+The `object` field contains your full structured output value. This maps Mastra's final structured output chunk into the AI SDK UI stream. Partial structured output chunks aren't emitted.
 
 ## Usage example
 

package/.docs/reference/auth/okta.md

@@ -54,7 +54,7 @@ export const mastra = new Mastra({
 
 ### Environment variables
 
-The following environment variables are automatically used when constructor options are not provided:
+The following environment variables are automatically used when constructor options aren't provided:
 
 **OKTA\_DOMAIN** (`string`): Your Okta domain (e.g., \`dev-123456.okta.com\`). Found in your Okta admin console.
 

package/.docs/reference/auth/workos.md

@@ -81,7 +81,7 @@ const auth = new MastraAuthWorkos({
 })
 ```
 
-When `trustJwtClaims` is enabled, Mastra can authenticate verified bearer tokens for service principals even if `getUser()` is not the right lookup path. This is the preferred way to pass pre-resolved `organizationMembershipId` values into FGA checks for machine-to-machine flows.
+When `trustJwtClaims` is enabled, Mastra can authenticate verified bearer tokens for service principals even if `getUser()` isn't the right lookup path. This is the preferred way to pass pre-resolved `organizationMembershipId` values into FGA checks for machine-to-machine flows.
 
 ## Custom authorization
 

package/.docs/reference/browser/agent-browser.md

@@ -363,7 +363,7 @@ Capture a screenshot of the current page as PNG (viewport by default; set `fullP
 
 | Parameter  | Type      | Description                                                                              |
 | ---------- | --------- | ---------------------------------------------------------------------------------------- |
-| `fullPage` | `boolean` | Capture the full scrollable page instead of just the viewport (optional, default: false) |
+| `fullPage` | `boolean` | Capture the full scrollable page instead of only the viewport (optional, default: false) |
 
 ### `browser_close`
 

package/.docs/reference/browser/browser-viewer.md

@@ -8,6 +8,7 @@ Use `BrowserViewer` when your agent drives a browser through a CLI tool like `br
 
 ```typescript
 import { Workspace, LocalSandbox } from '@mastra/core/workspace'
+import { Memory } from '@mastra/memory'
 import { BrowserViewer } from '@mastra/browser-viewer'
 import { Agent } from '@mastra/core/agent'
 
@@ -26,6 +27,7 @@ const browserAgent = new Agent({
   model: 'openai/gpt-5.5',
   workspace,
   instructions: 'You are a web automation assistant.',
+  memory: new Memory(),
 })
 ```
 
@@ -42,7 +44,7 @@ When `cdpUrl` is provided, `BrowserViewer` connects to the existing browser inst
 
 ## Constructor parameters
 
-**cli** (`'agent-browser' | 'browser-use' | 'browse-cli'`): Which CLI the agent uses for browser automation. The CLI connects to Chrome via the CDP URL.
+**cli** (`'agent-browser' | 'browser-use' | 'browse' | 'browse-cli'`): Which CLI the agent uses for browser automation. The CLI connects to Chrome via the CDP URL.
 
 **headless** (`boolean`): Whether to run Chrome in headless mode. (Default: `true`)
 
@@ -72,7 +74,7 @@ When `cdpUrl` is provided, `BrowserViewer` connects to the existing browser inst
 
 **providerType** (`'cli'`): Always 'cli'. Distinguishes BrowserViewer from SDK-based providers like AgentBrowser.
 
-**cli** (`'agent-browser' | 'browser-use' | 'browse-cli'`): The CLI provider this instance is configured for.
+**cli** (`'agent-browser' | 'browser-use' | 'browse' | 'browse-cli'`): The CLI provider this instance is configured for.
 
 **status** (`BrowserStatus`): Current browser status: 'pending', 'launching', 'ready', 'error', 'closing', or 'closed'.
 
@@ -192,9 +194,9 @@ await viewer.injectKeyboardEvent({
 
 Each CLI must be installed separately. Each also publishes a [skill](https://mastra.ai/docs/workspace/skills) that teaches the agent its commands and workflows. When a CLI command runs through `workspace_execute_command`, Mastra detects it and injects the CDP URL automatically using the correct flag.
 
-Unlike SDK providers, `BrowserViewer` does not provide agent tools. The agent uses CLI commands through `workspace_execute_command` instead.
+Unlike SDK providers, `BrowserViewer` doesn't provide agent tools. The agent uses CLI commands through `workspace_execute_command` instead.
 
-### [agent-browser](https://www.npmjs.com/package/agent-browser)
+### [`agent-browser`](https://www.npmjs.com/package/agent-browser)
 
 Config value: `'agent-browser'` · CDP flag: `--cdp`
 
@@ -203,7 +205,7 @@ npm install -g agent-browser
 npx skills add vercel-labs/agent-browser
 ```
 
-### [browser-use](https://pypi.org/project/browser-use/)
+### [`browser-use`](https://pypi.org/project/browser-use/)
 
 Config value: `'browser-use'` · CDP flag: `--cdp-url`
 
@@ -212,13 +214,13 @@ pip install browser-use
 npx skills add browser-use/browser-use --skill browser-use
 ```
 
-### [browse-cli](https://www.npmjs.com/package/@browserbasehq/browse-cli) (command: `browse`)
+### [`browse`](https://www.npmjs.com/package/browse) (command: `browse`)
 
-Config value: `'browse-cli'` · CDP flag: `--ws`
+Config value: `'browse'` · CDP flag: `--ws`
 
 ```bash
-npm install -g @browserbasehq/browse-cli
-npx skills add browserbase/skills
+npm install -g browse
+browse skills install
 ```
 
 ## Related

package/.docs/reference/browser/stagehand-browser.md

@@ -248,7 +248,7 @@ Capture a screenshot of the current page as PNG (viewport by default; set `fullP
 
 | Parameter  | Type      | Description                                                                              |
 | ---------- | --------- | ---------------------------------------------------------------------------------------- |
-| `fullPage` | `boolean` | Capture the full scrollable page instead of just the viewport (optional, default: false) |
+| `fullPage` | `boolean` | Capture the full scrollable page instead of only the viewport (optional, default: false) |
 
 ### `stagehand_close`
 

package/.docs/reference/cli/mastra.md

@@ -1222,7 +1222,9 @@ Prints help message and exits.
 
 By default, Mastra collects anonymous information about your project like your OS, Mastra version or Node.js version. You can read the [source code](https://github.com/mastra-ai/mastra/blob/main/packages/cli/src/analytics/index.ts) to check what's collected.
 
-You can opt out of the CLI analytics by setting an environment variable:
+When a server started with `mastra dev` or `mastra start` has observability metrics enabled, Mastra also sends anonymous, aggregated model usage at startup: input and output token counts per provider and model, plus the command (`dev` or `start`) and `NODE_ENV`. No prompts, responses, or other message content is ever sent. You can read the [source code](https://github.com/mastra-ai/mastra/blob/main/packages/core/src/telemetry/usage-telemetry.ts) to check what's collected.
+
+You can opt out of all CLI and usage analytics by setting an environment variable:
 
 ```bash
 MASTRA_TELEMETRY_DISABLED=1

package/.docs/reference/client-js/responses.md

@@ -130,7 +130,7 @@ Use [`client.conversations`](https://mastra.ai/reference/client-js/conversations
 
 `response.tools` contains the configured function definitions available for the request.
 
-If the model calls a function, that activity appears in `response.output` as `function_call` and `function_call_output` items alongside the final assistant `message`.
+If the model calls a function, that activity is included in `response.output` as `function_call` and `function_call_output` items alongside the final assistant `message`.
 
 When `stream: true`, function calls are also emitted as Responses stream events. Read `response.function_call_arguments.delta` events for partial argument chunks and prefer `response.function_call_arguments.done` for the finalized arguments payload and tool name. Read `response.output_item.done` events for completed `function_call` and `function_call_output` items. Tool output items use `<toolCallId>:output` IDs.
 
@@ -167,7 +167,7 @@ const response = await client.responses.create({
 
 ## Provider-backed requests
 
-Use `providerOptions` when you need provider-specific options that Mastra does not normalize at the Responses layer.
+Use `providerOptions` when you need provider-specific options that Mastra doesn't normalize at the Responses layer.
 
 ```typescript
 const response = await client.responses.create({

package/.docs/reference/client-js/workflows.md

@@ -243,7 +243,7 @@ await mastraClient.pauseSchedule('daily-report')
 
 ### `resumeSchedule()`
 
-Resume a paused schedule. The next fire time is recomputed from now, so a long-paused schedule does not fire a backlog. Returns the updated schedule. Idempotent.
+Resume a paused schedule. The next fire time is recomputed from now, so a long-paused schedule doesn't fire a backlog. Returns the updated schedule. Idempotent.
 
 ```typescript
 await mastraClient.resumeSchedule('daily-report')

package/.docs/reference/configuration.md

@@ -637,7 +637,7 @@ export const mastra = new Mastra({
 **Type:** `object`\
 **Default:** `undefined`
 
-MCP transport options applied to all MCP HTTP and SSE routes. Use this to enable stateless mode for serverless environments (Cloudflare Workers, Vercel Edge, AWS Lambda, etc.) where persistent connections and in-memory session state are not available.
+MCP transport options applied to all MCP HTTP and SSE routes. Use this to enable stateless mode for serverless environments (Cloudflare Workers, Vercel Edge, AWS Lambda, etc.) where persistent connections and in-memory session state aren't available.
 
 | Property             | Type           | Default     | Description                                          |
 | -------------------- | -------------- | ----------- | ---------------------------------------------------- |

package/.docs/reference/core/removeWorkspace.md

@@ -0,0 +1,26 @@
+# Mastra.removeWorkspace()
+
+The `.removeWorkspace()` method removes a workspace from the Mastra runtime registry. Pass `{ destroy: true }` to destroy the workspace before it's removed.
+
+## Usage example
+
+```typescript
+await mastra.removeWorkspace('workspace-123', { destroy: true })
+```
+
+## Parameters
+
+**id** (`string`): The ID of the workspace to remove.
+
+**options** (`{ destroy?: boolean }`): Optional cleanup behavior. Set \`destroy\` to \`true\` to call \`workspace.destroy()\` before removing the workspace.
+
+## Returns
+
+**removed** (`Promise<boolean>`): \`true\` when a workspace was removed. \`false\` when no workspace exists for the ID.
+
+When `destroy` is `true` and `workspace.destroy()` throws, the call rejects with that error and the workspace remains registered so the caller can retry cleanup.
+
+## Related
+
+- [Workspace overview](https://mastra.ai/docs/workspace/overview)
+- [Workspace class](https://mastra.ai/reference/workspace/workspace-class)

package/.docs/reference/editor/browser-provider.md

@@ -2,7 +2,7 @@
 
 `BrowserProvider` is the interface a package implements to register a browser with [`MastraEditor`](https://mastra.ai/reference/editor/mastra-editor). The editor calls `createBrowser(config)` at agent hydration time, using the `provider` id from the stored [`StorageBrowserRef`](https://mastra.ai/reference/editor/storage-browser-ref) as the lookup key.
 
-There are no built-in browser providers. To use the `browser` feature in the Agent Builder, register a provider package (for example, `@mastra/stagehand`).
+No built-in browser providers are available. To use the `browser` feature in the Agent Builder, register a provider package (for example, `@mastra/stagehand`).
 
 ## Usage example
 

package/.docs/reference/editor/storage-browser-ref.md

@@ -2,7 +2,7 @@
 
 `StorageBrowserRef` is the inline browser configuration attached to a stored agent. The `provider` id is resolved at hydration time against the [`BrowserProvider`](https://mastra.ai/reference/editor/browser-provider) registered on [`MastraEditor.browsers`](https://mastra.ai/reference/editor/mastra-editor).
 
-It is the type used by [`BuilderAgentDefaults.browser`](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) and by stored agent records.
+It's the type used by [`BuilderAgentDefaults.browser`](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) and by stored agent records.
 
 ## Usage example
 
@@ -36,7 +36,7 @@ new MastraEditor({
 type StorageBrowserRef = { type: 'inline'; config: StorageBrowserConfig }
 ```
 
-There is no `{ type: 'id' }` variant for browsers — they are always inlined.
+A `{ type: 'id' }` variant for browsers isn't available — they're always inlined.
 
 ## Properties
 
@@ -70,7 +70,7 @@ The shape embedded under `config`. Defined in `@mastra/core/storage`.
 
 ## Hydration
 
-`StorageBrowserRef` is resolved lazily on `mastra.editor.agent.getById()`. The editor looks up `config.provider` on `MastraEditor.browsers` and calls `provider.createBrowser(config)`. If the provider is not registered, the editor logs a warning and returns `undefined` — the agent still loads, but without a browser.
+`StorageBrowserRef` is resolved lazily on `mastra.editor.agent.getById()`. The editor looks up `config.provider` on `MastraEditor.browsers` and calls `provider.createBrowser(config)`. If the provider isn't registered, the editor logs a warning and returns `undefined` — the agent still loads, but without a browser.
 
 ## Related
 

package/.docs/reference/editor/storage-workspace-ref.md

@@ -2,7 +2,7 @@
 
 `StorageWorkspaceRef` is the discriminated union used to attach a workspace to a stored agent. It either points at a workspace registered on the Mastra runtime by ID, or embeds a workspace snapshot inline.
 
-It is the type used by [`BuilderAgentDefaults.workspace`](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) and by stored agent records.
+It's the type used by [`BuilderAgentDefaults.workspace`](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) and by stored agent records.
 
 ## Usage example
 

package/.docs/reference/evals/rubric.md

@@ -0,0 +1,113 @@
+# Rubric scorer
+
+**Added in:** `@mastra/evals@1.3.0`
+
+The `createRubricScorer()` function creates an LLM-as-judge scorer that grades an agent's output against a rubric (a checklist of criteria). It returns a **binary** score: `1` only when every required criterion is satisfied, otherwise `0`. The `reason` lists each criterion's verdict so the agent knows exactly what to fix.
+
+This scorer is designed to drop into [`isTaskComplete`](https://mastra.ai/reference/streaming/agents/stream). Because `isTaskComplete` treats `score === 1` as "task complete" and injects the `reason` back into the conversation as feedback, the agent keeps iterating until the rubric is satisfied (or `maxSteps` is reached).
+
+## Parameters
+
+**model** (`MastraModelConfig`): The language model used to grade the output against the rubric. A smaller, cheaper model is usually sufficient for grading.
+
+**criteria** (`RubricCriterion[] | string`): The rubric to grade against. A string is treated as a newline-delimited checklist (each line becomes a required criterion). If omitted, the rubric is read at run time from a \`rubric\` value on request/additional context; if none resolves, the scorer is a no-op and returns 1.
+
+**options** (`RubricScorerOptions`): Configuration options for the scorer
+
+## `.run()` returns
+
+**score** (`number`): 1 when every required criterion is satisfied, otherwise 0 (multiplied by scale).
+
+**reason** (`string`): A per-criterion explanation listing which criteria are met or unmet and why. This is the text that isTaskComplete injects back into the conversation as feedback.
+
+## Usage with isTaskComplete
+
+Define the rubric once, attach the scorer to `isTaskComplete`, and the agent self-corrects until the rubric is satisfied:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createRubricScorer } from '@mastra/evals/scorers/prebuilt'
+
+const supervisor = new Agent({
+  id: 'supervisor',
+  instructions: `You coordinate research and writing using specialized agents. Delegate to research-agent for facts, then writing-agent for content.`,
+  model: 'openai/gpt-5.5',
+  agents: { researchAgent, writingAgent },
+})
+
+const rubricScorer = createRubricScorer({
+  model: 'openai/gpt-5-mini',
+  criteria: [
+    { description: 'The response includes an analysis section' },
+    { description: 'The response includes concrete recommendations' },
+  ],
+})
+
+const stream = await supervisor.stream('Research AI in education', {
+  maxSteps: 10,
+  isTaskComplete: {
+    scorers: [rubricScorer],
+    strategy: 'all',
+  },
+})
+```
+
+## String rubric
+
+A newline-delimited string is parsed into criteria, with common list markers (`-`, `*`, `1.`) stripped. Every line becomes a required criterion:
+
+```typescript
+const rubricScorer = createRubricScorer({
+  model: 'openai/gpt-5-mini',
+  criteria: `- All tests pass in the test suite
+- The function is named find_duplicates and accepts a single list argument`,
+})
+```
+
+## Optional criteria
+
+Mark a criterion as optional to have it graded and reported without gating completion:
+
+```typescript
+const rubricScorer = createRubricScorer({
+  model: 'openai/gpt-5-mini',
+  criteria: [
+    { description: 'Includes an analysis section', required: true },
+    { description: 'Includes citations', required: false },
+  ],
+})
+```
+
+## Dynamic rubric per run
+
+When no `criteria` is passed to the factory, the scorer resolves a `rubric` value from the run's request context, additional context, or input. This lets a single scorer instance grade different rubrics per run without rebuilding it:
+
+```typescript
+const rubricScorer = createRubricScorer({
+  model: 'openai/gpt-5-mini',
+})
+
+await supervisor.stream('Write find_duplicates', {
+  isTaskComplete: { scorers: [rubricScorer] },
+  requestContext: {
+    rubric: '- All tests pass\n- The function is named find_duplicates',
+  },
+})
+```
+
+If no rubric resolves, the scorer returns `1` and doesn't gate the loop.
+
+## Scoring details
+
+The scorer runs in two phases:
+
+1. **Grade**: The judge model evaluates each criterion independently and returns a per-criterion verdict (`satisfied` / not) with reasoning.
+2. **Score**: The result is `1` only when every required criterion is `satisfied`, otherwise `0`. If no criteria are marked required, all criteria are treated as required.
+
+The `reason` summarizes the overall result and lists each criterion with its verdict, so a failing grade gives the agent targeted, actionable feedback rather than a generic "try again".
+
+## Related
+
+- [isTaskComplete on stream()](https://mastra.ai/reference/streaming/agents/stream)
+- [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents)
+- [createScorer](https://mastra.ai/reference/evals/create-scorer)

package/.docs/reference/evals/trajectory-accuracy.md

@@ -31,7 +31,7 @@ workflow_run
 
 ### Fallback extraction
 
-When storage is not available, the pipeline falls back to:
+When storage isn't available, the pipeline falls back to:
 
 - **Agents:** `extractTrajectory()` — Extracts `ToolCallStep` entries from `toolInvocations` in the agent's message output. Produces a flat list of tool calls.
 - **Workflows:** `extractWorkflowTrajectory()` — Extracts `WorkflowStepStep` entries from `stepResults`. Produces a flat list of workflow steps.
@@ -176,7 +176,7 @@ In this example, the parent workflow requires strict ordering of its steps, but
 ### Use the LLM-based scorer when:
 
 - You need **semantic understanding** of whether steps were appropriate
-- The optimal trajectory is **not predetermined** (evaluate based on task requirements)
+- The optimal trajectory **isn't predetermined** (evaluate based on task requirements)
 - You want to detect **unnecessary, redundant, or missing** steps
 - You need **explanations** for scoring decisions
 - You are evaluating **production agent behavior**
@@ -360,7 +360,7 @@ console.log(result.scores.trajectory['trajectory-accuracy'])
 
 ### Comparing step data
 
-Validates not just the step names but also step-specific data. For tool calls, this compares `toolArgs` and `toolResult`. For workflow steps, this compares `output`.
+Validates the step names and step-specific data. For tool calls, this compares `toolArgs` and `toolResult`. For workflow steps, this compares `output`.
 
 ```typescript
 const scorer = createTrajectoryAccuracyScorerCode({

package/.docs/reference/harness/harness-class.md

@@ -166,10 +166,9 @@ const displayState = harness.getDisplayState()
 
 Restore the task portion of `HarnessDisplayState` after a UI replays persisted task tool history. This emits `display_state_changed` without emitting a live `task_updated` event.
 
-If later task tools should read the replayed tasks, persist the same task list with `setState({ tasks })` before calling `restoreDisplayTasks(tasks)`.
+The task list itself is held in the thread-scoped `tasks` storage domain (the task store) and projected onto the agent state-signal lane (`stateId: "tasks"`), not in Harness state, so this method only updates the display snapshot. Task tools read and write the task store directly; you no longer need to seed `setState({ tasks })`.
 
 ```typescript
-await harness.setState({ tasks: replayedTasks })
 harness.restoreDisplayTasks(replayedTasks)
 ```
 
@@ -476,31 +475,50 @@ harness.respondToToolApproval({ decision: 'approve' })
 harness.respondToToolApproval({ decision: 'decline' })
 ```
 
-### Questions and plans
+### Tool suspensions and plans
 
-#### `respondToQuestion({ questionId, answer })`
+#### `respondToToolSuspension({ resumeData, toolCallId?, requestContext? })`
 
-Respond to a pending question from the `ask_user` built-in tool.
+Respond to a pending tool suspension. Interactive built-in tools such as `ask_user` and `request_access` pause through the native tool-suspension primitive, which emits a `tool_suspended` event carrying `toolCallId`, `toolName`, and `suspendPayload`. Pass `resumeData` to resume the suspended tool with the user's response.
+
+Provide `toolCallId` to select which suspension to resume. It is required when more than one tool is suspended at the same time (for example, parallel `ask_user` calls). When omitted, it resolves to the sole pending suspension.
 
 ```typescript
-harness.respondToQuestion({ questionId: 'q-123', answer: 'Yes, proceed with the refactor' })
+harness.subscribe(event => {
+  if (event.type === 'tool_suspended' && event.toolName === 'ask_user') {
+    const { question } = event.suspendPayload as { question: string }
+    // Show `question` to the user, then resume the tool with their answer.
+    harness.respondToToolSuspension({
+      toolCallId: event.toolCallId,
+      resumeData: 'Yes, proceed with the refactor',
+    })
+  }
+})
 ```
 
 For multi-select questions, pass the selected option labels as a string array.
 
 ```typescript
-harness.respondToQuestion({ questionId: 'q-123', answer: ['Add tests', 'Update docs'] })
+harness.respondToToolSuspension({
+  toolCallId: event.toolCallId,
+  resumeData: ['Add tests', 'Update docs'],
+})
 ```
 
-#### `respondToPlanApproval({ planId, response })`
+#### Responding to a submitted plan
+
+The `submit_plan` built-in tool pauses via the native tool-suspension primitive, so it surfaces through the same `tool_suspended` event as other interactive tools. Resume it with [`respondToToolSuspension`](#respondtotoolsuspension-resumedata-toolcallid-requestcontext-), passing a `resumeData` object with `action` (`'approved'` or `'rejected'`) and an optional `feedback` string.
 
-Respond to a pending plan approval from the `submit_plan` built-in tool. The `response` object contains `action` (`'approved'` or `'rejected'`) and an optional `feedback` string.
+On approval, the Harness automatically switches to its default (execution) mode. On rejection, the plan-mode run resumes so the agent can revise and submit again.
 
 ```typescript
-harness.respondToPlanApproval({ planId: 'plan-123', response: { action: 'approved' } })
-harness.respondToPlanApproval({
-  planId: 'plan-123',
-  response: { action: 'rejected', feedback: 'Needs more detail' },
+harness.respondToToolSuspension({
+  toolCallId: event.toolCallId,
+  resumeData: { action: 'approved' },
+})
+harness.respondToToolSuspension({
+  toolCallId: event.toolCallId,
+  resumeData: { action: 'rejected', feedback: 'Needs more detail' },
 })
 ```
 
@@ -767,7 +785,7 @@ unsubscribe()
 
 Returns: `() => void`
 
-`subscribeDisplayState()` does not call the listener immediately. Call [`getDisplayState`](#getdisplaystate) first if the UI needs an initial render before the next harness event.
+`subscribeDisplayState()` doesn't call the listener immediately. Call [`getDisplayState`](#getdisplaystate) first if the UI needs an initial render before the next harness event.
 
 #### `subscribe(listener)`
 
@@ -798,48 +816,46 @@ unsubscribe()
 
 The harness emits events through registered listeners. The following table lists the available event types:
 
-| Event type                 | Description                                                                                         |
-| -------------------------- | --------------------------------------------------------------------------------------------------- |
-| `mode_changed`             | The active mode changed.                                                                            |
-| `model_changed`            | The active model changed.                                                                           |
-| `thread_changed`           | The active thread changed.                                                                          |
-| `thread_created`           | A new thread was created.                                                                           |
-| `thread_deleted`           | A thread was deleted.                                                                               |
-| `state_changed`            | Harness state was updated.                                                                          |
-| `agent_start`              | The agent started processing.                                                                       |
-| `agent_end`                | The agent finished processing.                                                                      |
-| `message_start`            | A new message started streaming.                                                                    |
-| `message_update`           | A message was updated with new content.                                                             |
-| `message_end`              | A message finished streaming.                                                                       |
-| `tool_start`               | A tool call started.                                                                                |
-| `tool_approval_required`   | A tool call requires user approval.                                                                 |
-| `tool_update`              | A tool call was updated with progress.                                                              |
-| `tool_end`                 | A tool call finished.                                                                               |
-| `tool_input_start`         | Tool input started streaming.                                                                       |
-| `tool_input_delta`         | Tool input received a streaming delta.                                                              |
-| `tool_input_end`           | Tool input finished streaming.                                                                      |
-| `usage_update`             | Token usage was updated.                                                                            |
-| `error`                    | An error occurred.                                                                                  |
-| `info`                     | An informational message was emitted.                                                               |
-| `follow_up_queued`         | A follow-up message was queued.                                                                     |
-| `workspace_status_changed` | The workspace status changed.                                                                       |
-| `workspace_ready`          | The workspace finished initializing.                                                                |
-| `workspace_error`          | The workspace encountered an error.                                                                 |
-| `om_status`                | Observational Memory status update.                                                                 |
-| `om_observation_start`     | An observation started.                                                                             |
-| `om_observation_end`       | An observation completed.                                                                           |
-| `om_reflection_start`      | A reflection started.                                                                               |
-| `om_reflection_end`        | A reflection completed.                                                                             |
-| `ask_question`             | The agent asked a question via the `ask_user` tool. Includes optional choices and a selection mode. |
-| `plan_approval_required`   | The agent submitted a plan for approval via the `submit_plan` tool.                                 |
-| `plan_approved`            | A plan was approved.                                                                                |
-| `subagent_start`           | A subagent started processing.                                                                      |
-| `subagent_text_delta`      | A subagent emitted a text delta.                                                                    |
-| `subagent_tool_start`      | A subagent started a tool call.                                                                     |
-| `subagent_tool_end`        | A subagent finished a tool call.                                                                    |
-| `subagent_end`             | A subagent finished processing.                                                                     |
-| `subagent_model_changed`   | A subagent's model changed.                                                                         |
-| `task_updated`             | A task list was updated.                                                                            |
+| Event type                 | Description                                                                                                                                                                                                                                                                               |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mode_changed`             | The active mode changed.                                                                                                                                                                                                                                                                  |
+| `model_changed`            | The active model changed.                                                                                                                                                                                                                                                                 |
+| `thread_changed`           | The active thread changed.                                                                                                                                                                                                                                                                |
+| `thread_created`           | A new thread was created.                                                                                                                                                                                                                                                                 |
+| `thread_deleted`           | A thread was deleted.                                                                                                                                                                                                                                                                     |
+| `state_changed`            | Harness state was updated.                                                                                                                                                                                                                                                                |
+| `agent_start`              | The agent started processing.                                                                                                                                                                                                                                                             |
+| `agent_end`                | The agent finished processing.                                                                                                                                                                                                                                                            |
+| `message_start`            | A new message started streaming.                                                                                                                                                                                                                                                          |
+| `message_update`           | A message was updated with new content.                                                                                                                                                                                                                                                   |
+| `message_end`              | A message finished streaming.                                                                                                                                                                                                                                                             |
+| `tool_start`               | A tool call started.                                                                                                                                                                                                                                                                      |
+| `tool_approval_required`   | A tool call requires user approval.                                                                                                                                                                                                                                                       |
+| `tool_suspended`           | A tool paused via the native tool-suspension primitive (for example `ask_user`, `request_access`, or `submit_plan`). Includes `toolCallId`, `toolName`, and `suspendPayload`. Resume it with [`respondToToolSuspension`](#respondtotoolsuspension-resumedata-toolcallid-requestcontext-). |
+| `tool_update`              | A tool call was updated with progress.                                                                                                                                                                                                                                                    |
+| `tool_end`                 | A tool call finished.                                                                                                                                                                                                                                                                     |
+| `tool_input_start`         | Tool input started streaming.                                                                                                                                                                                                                                                             |
+| `tool_input_delta`         | Tool input received a streaming delta.                                                                                                                                                                                                                                                    |
+| `tool_input_end`           | Tool input finished streaming.                                                                                                                                                                                                                                                            |
+| `usage_update`             | Token usage was updated.                                                                                                                                                                                                                                                                  |
+| `error`                    | An error occurred.                                                                                                                                                                                                                                                                        |
+| `info`                     | An informational message was emitted.                                                                                                                                                                                                                                                     |
+| `follow_up_queued`         | A follow-up message was queued.                                                                                                                                                                                                                                                           |
+| `workspace_status_changed` | The workspace status changed.                                                                                                                                                                                                                                                             |
+| `workspace_ready`          | The workspace finished initializing.                                                                                                                                                                                                                                                      |
+| `workspace_error`          | The workspace encountered an error.                                                                                                                                                                                                                                                       |
+| `om_status`                | Observational Memory status update.                                                                                                                                                                                                                                                       |
+| `om_observation_start`     | An observation started.                                                                                                                                                                                                                                                                   |
+| `om_observation_end`       | An observation completed.                                                                                                                                                                                                                                                                 |
+| `om_reflection_start`      | A reflection started.                                                                                                                                                                                                                                                                     |
+| `om_reflection_end`        | A reflection completed.                                                                                                                                                                                                                                                                   |
+| `subagent_start`           | A subagent started processing.                                                                                                                                                                                                                                                            |
+| `subagent_text_delta`      | A subagent emitted a text delta.                                                                                                                                                                                                                                                          |
+| `subagent_tool_start`      | A subagent started a tool call.                                                                                                                                                                                                                                                           |
+| `subagent_tool_end`        | A subagent finished a tool call.                                                                                                                                                                                                                                                          |
+| `subagent_end`             | A subagent finished processing.                                                                                                                                                                                                                                                           |
+| `subagent_model_changed`   | A subagent's model changed.                                                                                                                                                                                                                                                               |
+| `task_updated`             | A task list was updated.                                                                                                                                                                                                                                                                  |
 
 ## Built-in tools
 
@@ -859,15 +875,18 @@ The harness provides built-in tools to agents in every mode:
 
 The `ask_user` tool accepts `options` for choice prompts. Set `selectionMode` to `single_select` to let the user pick one option, or `multi_select` to let the user pick multiple options. When `options` are provided and `selectionMode` is omitted, the prompt defaults to `single_select`. Omit `options` for free-text questions.
 
-The following example demonstrates a multi-select response handler. The UI reads `event.selectionMode`, lets the user choose multiple options, then returns a string array with `respondToQuestion()`.
+The following example demonstrates a multi-select response handler. The tool pauses through the `tool_suspended` event, the UI reads `selectionMode` from `event.suspendPayload`, lets the user choose multiple options, then returns a string array with `respondToToolSuspension()`.
 
 ```typescript
 harness.subscribe(event => {
-  if (event.type === 'ask_question' && event.selectionMode === 'multi_select') {
-    harness.respondToQuestion({
-      questionId: event.questionId,
-      answer: ['Add tests', 'Update docs'],
-    })
+  if (event.type === 'tool_suspended' && event.toolName === 'ask_user') {
+    const { selectionMode } = event.suspendPayload as { selectionMode?: string }
+    if (selectionMode === 'multi_select') {
+      harness.respondToToolSuspension({
+        toolCallId: event.toolCallId,
+        resumeData: ['Add tests', 'Update docs'],
+      })
+    }
   }
 })
 ```