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

package/.docs/docs/server/auth/okta.md

@@ -22,7 +22,7 @@ OKTA_COOKIE_PASSWORD=a-random-string-at-least-32-characters-long
 OKTA_API_TOKEN=your-api-token
 ```
 
-> **Note:** `OKTA_COOKIE_PASSWORD` encrypts session cookies. If omitted, an auto-generated value is used that does not survive server restarts. Set it explicitly for production.
+> **Note:** `OKTA_COOKIE_PASSWORD` encrypts session cookies. If omitted, an auto-generated value is used that doesn't survive server restarts. Set it explicitly for production.
 >
 > `OKTA_API_TOKEN` is only required when using `MastraRBACOkta` to map Okta groups to permissions.
 
@@ -142,7 +142,7 @@ const rbac = new MastraRBACOkta({
 })
 ```
 
-The `_default` key assigns permissions to users whose Okta groups do not match any other key.
+The `_default` key assigns permissions to users whose Okta groups don't match any other key.
 
 ## Client-side setup
 

package/.docs/docs/server/auth/workos.md

@@ -125,7 +125,7 @@ const workosAuth = new MastraAuthWorkos({
 })
 ```
 
-This is useful when your JWT template already includes the exact FGA context Mastra needs, such as `organizationMembershipId`, tenant IDs, or service-principal identifiers. When `trustJwtClaims` is enabled, Mastra can fall back to those verified claims if a bearer token is not meant to round-trip through `workos.userManagement.getUser()`.
+This is useful when your JWT template already includes the exact FGA context Mastra needs, such as `organizationMembershipId`, tenant IDs, or service-principal identifiers. When `trustJwtClaims` is enabled, Mastra can fall back to those verified claims if a bearer token isn't meant to round-trip through `workos.userManagement.getUser()`.
 
 ### Custom authorization
 

package/.docs/docs/server/custom-api-routes.md

@@ -264,7 +264,7 @@ For more information about authentication providers, see the [Auth documentation
 
 Built-in streaming helpers such as [`chatRoute()`](https://mastra.ai/reference/ai-sdk/chat-route) forward the incoming request's `AbortSignal` to `agent.stream()`. That's the right default when a browser disconnect should cancel the model call.
 
-For custom streaming routes that should stop when the client disconnects, pass `c.req.raw.signal` to long-running work such as `agent.stream()`. Mastra's Node-based adapters also stop reading streamed `Response` bodies from custom routes when the client connection closes. Streamed response body errors that are not caused by client disconnects still propagate through the adapter's normal error handling. In Hono, disconnect behavior depends on the host runtime forwarding connection closes to `request.signal`.
+For custom streaming routes that should stop when the client disconnects, pass `c.req.raw.signal` to long-running work such as `agent.stream()`. Mastra's Node-based adapters also stop reading streamed `Response` bodies from custom routes when the client connection closes. Streamed response body errors that aren't caused by client disconnects still propagate through the adapter's normal error handling. In Hono, disconnect behavior depends on the host runtime forwarding connection closes to `request.signal`.
 
 ```typescript
 registerApiRoute('/stream', {

package/.docs/docs/server/pubsub.md

@@ -27,7 +27,7 @@ Subscribers can also opt into work distribution. A group of subscribers that sha
 
 ## Default backend
 
-When you do not set the `pubsub` option, Mastra uses [`EventEmitterPubSub`](https://mastra.ai/reference/pubsub/event-emitter). It delivers events in process using a Node.js [`EventEmitter`](https://nodejs.org/api/events.html#class-eventemitter), so it works without any external service.
+When you don't set the `pubsub` option, Mastra uses [`EventEmitterPubSub`](https://mastra.ai/reference/pubsub/event-emitter). It delivers events in process using a Node.js [`EventEmitter`](https://nodejs.org/api/events.html#class-eventemitter), so it works without any external service.
 
 ```typescript
 import { Mastra } from '@mastra/core'
@@ -36,11 +36,11 @@ import { Mastra } from '@mastra/core'
 export const mastra = new Mastra({})
 ```
 
-Because it runs in process, events are not persisted and do not reach other processes. The default suits a single instance, which covers most applications.
+Because it runs in process, events aren't persisted and don't reach other processes. The default suits a single instance, which covers most applications.
 
 ## Choosing a backend
 
-Set the `pubsub` option on the `Mastra` instance to choose a backend. Each backend implements the same [`PubSub`](https://mastra.ai/reference/pubsub/base) contract, so the rest of your application does not change.
+Set the `pubsub` option on the `Mastra` instance to choose a backend. Each backend implements the same [`PubSub`](https://mastra.ai/reference/pubsub/base) contract, so the rest of your application doesn't change.
 
 The deciding question is where the subscriber runs.
 
@@ -100,7 +100,7 @@ export const mastra = new Mastra({
 
 Resumable streams let a client reconnect and replay events it missed, which requires the backend to keep recent history. Distributed backends such as [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams) persist events, so they support replay on their own.
 
-In-process delivery does not keep history. To add replay on top of [`EventEmitterPubSub`](https://mastra.ai/reference/pubsub/event-emitter), wrap it in [`CachingPubSub`](https://mastra.ai/reference/pubsub/caching-pubsub), which records published events per topic so a late or reconnecting subscriber can catch up before continuing with live events.
+In-process delivery doesn't keep history. To add replay on top of [`EventEmitterPubSub`](https://mastra.ai/reference/pubsub/event-emitter), wrap it in [`CachingPubSub`](https://mastra.ai/reference/pubsub/caching-pubsub), which records published events per topic so a late or reconnecting subscriber can catch up before continuing with live events.
 
 ```typescript
 import { Mastra } from '@mastra/core'

package/.docs/docs/studio/auth.md

@@ -62,7 +62,7 @@ Studio handles the token as follows:
 
 - It reads `auth_header` once on load and sends the value as the `Authorization` header on every API request in that session.
 - It removes `auth_header` from the address bar while preserving other query parameters and the hash.
-- It keeps the token in memory only and never writes it to local storage, so the token stays transient and does not persist across page reloads.
+- It keeps the token in memory only and never writes it to local storage, so the token stays transient and doesn't persist across page reloads.
 
 The token rides in a URL parameter, so the host application is responsible for how that URL is generated and transmitted. URL parameters can be exposed through browser history, referrer headers, and server access logs.
 

package/.docs/docs/studio/observability.md

@@ -84,7 +84,7 @@ For hosted traces, logs, and metrics across projects and deploys, see [Observabi
 
 ## Metrics
 
-A dashboard that summarizes agent, workflow, and tool performance over a configurable time range (last 24 hours to 30 days). The top row shows total agent runs, model cost, token consumption, and average scorer performance. Below that, detailed cards break down model usage and cost per model, token usage per agent, trace volume with completed and error counts, latency percentiles (p50 and p95), and scorer trends over time.
+A dashboard that summarizes agent, workflow, and tool performance over a configurable time range (last 24 hours to 30 days). The top row shows total agent runs, model cost, token consumption, and average scorer performance. Below that, detailed cards break down model usage and cost per model, token usage per agent, token usage over time with estimated cost, trace volume with completed and error counts, latency percentiles (p50 and p95), and scorer trends over time.
 
 Visit the [metrics overview](https://mastra.ai/docs/observability/metrics/overview) for more details.
 
@@ -96,6 +96,8 @@ When you run an agent or workflow, the Observability tab displays traces that hi
 
 Tracing filters out low-level framework details so your traces stay focused and readable. Visit the [tracing overview](https://mastra.ai/docs/observability/tracing/overview) for more details.
 
+To export a trace, select **Download trace JSON** in the trace panel header. This saves the entire trace as a `trace-<id>.json` file, with every span and its full input, output, metadata, and attributes. Use it to share a trace, attach it to a bug report, or build an evaluation dataset offline.
+
 ## Logs
 
 Browse internal Mastra logs forwarded to your observability storage. Logs provide full-text search (across message content, entity names, and trace IDs), date presets (last 24 hours to 30 days), and multi-select filters for level, entity type, and entity name. Selecting a log opens a detail panel showing the full message, structured data, and metadata. If the log is correlated with a trace, you can navigate directly to the trace and span timeline.

package/.docs/docs/workflows/scheduled-workflows.md

@@ -34,13 +34,13 @@ export const dailyReport = createWorkflow({
   .commit()
 ```
 
-There is no separate "register schedule" call. The scheduler reads `schedule` straight off the workflow when `Mastra` boots.
+A separate "register schedule" call won't happen. The scheduler reads `schedule` straight off the workflow when `Mastra` boots.
 
 ## What `schedule` changes
 
 A workflow that declares `schedule` is auto-promoted to the **evented execution engine**. The public API (`workflow.start()`, `workflow.startAsync()`, `streamLegacy()`, `resume()`) is unchanged — `EventedWorkflow extends Workflow` and overrides each method with matching signatures. From your code, scheduled fires and manual runs are indistinguishable.
 
-The promotion has one practical implication: evented runs require a storage adapter that supports concurrent updates, for example `@mastra/libsql`. If your adapter does not, `createRun()` throws a clear error pointing at the `schedule` field. Switch adapters or remove the schedule.
+The promotion has one practical implication: evented runs require a storage adapter that supports concurrent updates, for example `@mastra/libsql`. If your adapter doesn't, `createRun()` throws a clear error pointing at the `schedule` field. Switch adapters or remove the schedule.
 
 ## Single schedule
 
@@ -61,7 +61,7 @@ const dailyReport = createWorkflow({
 Fields:
 
 - `cron` (required): a 5-, 6-, or 7-part cron expression. Validated at workflow construction time.
-- `timezone` (optional): IANA timezone, for example `America/New_York`. Defaults to the host's local timezone. Set this explicitly in production so fire times do not depend on server locale.
+- `timezone` (optional): IANA timezone, for example `America/New_York`. Defaults to the host's local timezone. Set this explicitly in production so fire times don't depend on server locale.
 - `inputData` (optional): payload passed as the workflow's input on every fire.
 - `initialState` (optional): initial state for the run.
 - `requestContext` (optional): request context attached to the run.
@@ -105,14 +105,14 @@ Every fire records a trigger row with the run id, scheduled time, actual fire ti
 - The run's status (`running`, `success`, `failed`, `suspended`, `canceled`) as a badge.
 - The run's start time and duration.
 - A link to the run's full graph view at `/workflows/:workflowId/graph/:runId`.
-- A `pending` badge for triggers whose run record has not been written yet, due to a race between trigger publish and run snapshot.
-- A `publish failed` badge with the publish error when the scheduler could not enqueue the run at all.
+- A `pending` badge for triggers whose run record hasn't been written yet, due to a race between trigger publish and run snapshot.
+- A `publish failed` badge with the publish error when the scheduler couldn't enqueue the run at all.
 
-Triggers in a non-terminal state cause the panel to poll every five seconds until they reach a terminal state. The list paginates, so long-running schedules do not load thousands of rows up front.
+Triggers in a non-terminal state cause the panel to poll every five seconds until they reach a terminal state. The list paginates, so long-running schedules don't load thousands of rows up front.
 
 ## Pausing a schedule at runtime
 
-When a scheduled workflow misfires in production, you do not have to redeploy or hand-edit the database. Pause it from the SDK:
+When a scheduled workflow misfires in production, you don't have to redeploy or hand-edit the database. Pause it from the SDK:
 
 ```typescript
 import { MastraClient } from '@mastra/client-js'
@@ -132,8 +132,8 @@ In Studio, open the schedule detail page and select **Pause** or **Resume** in t
 A few rules worth knowing:
 
 - Pause is durable. The status is written to the schedules table and survives process restarts and redeploys. The declarative-config upsert never overwrites a user-set status, even when you change `cron`, `timezone`, or other fields.
-- Resume recomputes `nextFireAt` from now. A schedule paused for a week does not fire seven backlogged runs the moment you resume it. It fires on the next regular cron tick.
-- The only way to unpause is `resumeSchedule` (or the **Resume** button in Studio). Editing the workflow's `schedule` config does not unpause a paused row.
+- Resume recomputes `nextFireAt` from now. A schedule paused for a week doesn't fire seven backlogged runs the moment you resume it. It fires on the next regular cron tick.
+- The only way to unpause is `resumeSchedule` (or the **Resume** button in Studio). Editing the workflow's `schedule` config doesn't unpause a paused row.
 - Pause and resume are idempotent. Calling pause on an already-paused schedule is a no-op.
 - This is an operational override, not a way to author schedules. Creating, deleting, and editing schedules still happens in code via the `schedule` field on `createWorkflow`.
 
@@ -159,7 +159,7 @@ Deploy targets such as Fly Machines, Railway, Render, AWS ECS, GKE, or your own
 
 ### Serverless platforms
 
-Functions-as-a-service platforms such as Vercel, Netlify, AWS Lambda, and Cloudflare Workers shut the process down after each request. The tick loop never gets a second tick. Schedules declared in code do not fire on these platforms with the built-in scheduler today.
+Functions-as-a-service platforms such as Vercel, Netlify, AWS Lambda, and Cloudflare Workers shut the process down after each request. The tick loop never gets a second tick. Schedules declared in code don't fire on these platforms with the built-in scheduler today.
 
 On these platforms, use [`@mastra/inngest`](#inngest-workflows) instead. Inngest is serverless-native and holds the cron state for you.
 
@@ -169,9 +169,9 @@ The `schedule` field documented on this page drives Mastra's built-in scheduler.
 
 Practical implications:
 
-- Inngest schedules do not appear in Studio's `/workflows/schedules` view.
-- The workflow header **Schedules** action does not show for Inngest workflows.
-- `client.pauseSchedule` and `client.resumeSchedule` do not control Inngest schedules.
+- Inngest schedules don't appear in Studio's `/workflows/schedules` view.
+- The workflow header **Schedules** action doesn't show for Inngest workflows.
+- `client.pauseSchedule` and `client.resumeSchedule` don't control Inngest schedules.
 
 Manage Inngest schedules from the [Inngest dashboard](https://www.inngest.com/docs/guides/scheduled-functions). Use Mastra schedules when you want Mastra to own scheduling end to end.
 

package/.docs/docs/workspace/filesystem.md

@@ -148,7 +148,7 @@ const workspace = new Workspace({
 })
 ```
 
-> **Note:** `filesystem` and `mounts` are mutually exclusive. You cannot use a resolver function together with `mounts` in the same workspace.
+> **Note:** `filesystem` and `mounts` are mutually exclusive. You can't use a resolver function together with `mounts` in the same workspace.
 
 ## Read-only mode
 

package/.docs/docs/workspace/lsp.md

@@ -177,7 +177,7 @@ const workspace = new Workspace({
 - LSP inspection only works for file types with a matching built-in or custom language server
 - The `path` you inspect must resolve inside the workspace filesystem or allowed paths
 - External package inspection may resolve to declaration files such as `.d.ts` instead of runtime source files
-- `lsp_inspect` complements `view` and `search_content`, but does not replace reading implementation code when you need full context
+- `lsp_inspect` complements `view` and `search_content`, but doesn't replace reading implementation code when you need full context
 
 ## Related
 

package/.docs/docs/workspace/overview.md

@@ -80,6 +80,14 @@ export const myAgent = new Agent({
 })
 ```
 
+## Lifecycle and cleanup
+
+Mastra registers global and agent workspaces so they can be listed and retrieved at runtime. When you call `mastra.shutdown()`, Mastra destroys registered workspaces that it owns. This closes workspace resources such as language servers, browsers, sandbox processes, and filesystem provider handles.
+
+For manual cleanup, use [`mastra.removeWorkspace()`](https://mastra.ai/reference/core/removeWorkspace). Pass `{ destroy: true }` when the workspace should be destroyed before it's removed from the registry.
+
+Static providers are owned by the workspace. Resolver-backed providers are owned by your application because the workspace creates them at request time. See [dynamic sandbox lifecycle ownership](https://mastra.ai/docs/workspace/sandbox) for the resolver cleanup model.
+
 ## Configuration patterns
 
 Workspaces support several configuration patterns depending on what capabilities your agent needs. The two main building blocks are `filesystem` (file tools) and `sandbox` (command execution), with `mounts` as the way to bridge cloud storage into sandboxes.
@@ -266,7 +274,7 @@ const workspace = new Workspace({
 })
 ```
 
-Functions for `enabled` receive `{ requestContext, workspace }`. Functions for `requireApproval` and `requireReadBeforeWrite` also receive `args` since they are evaluated when the tool is called.
+Functions for `enabled` receive `{ requestContext, workspace }`. Functions for `requireApproval` and `requireReadBeforeWrite` also receive `args` since they're evaluated when the tool is called.
 
 ### Tool name remapping
 
@@ -291,6 +299,32 @@ const workspace = new Workspace({
 
 The agent sees `view`, `search_content`, `find_files`, `execute_command`, and `lsp_inspect` instead of the default `mastra_workspace_*` names. Tool names must be unique — duplicate names or conflicts with other default names throw an error.
 
+### Tool hooks
+
+Set `tools.hooks` to run logic before and after every enabled workspace tool call. Hooks run after name remapping, so the hook context includes both the exposed `toolName` and the original `workspaceToolName`:
+
+```typescript
+import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './workspace' }),
+  tools: {
+    hooks: {
+      beforeToolCall: ({ toolName, workspaceToolName, input }) => {
+        console.log(`Running ${toolName} (${workspaceToolName})`, input)
+      },
+      afterToolCall: ({ toolName, output, error }) => {
+        console.log(`Finished ${toolName}`, { output, error })
+      },
+    },
+  },
+})
+```
+
+Return `{ proceed: false, output }` from `beforeToolCall` to skip the tool call and use `output` as its result.
+
+If the owning agent also defines [tool hooks](https://mastra.ai/docs/agents/using-tools), workspace hooks run inside the agent hook wrapper: agent `beforeToolCall` first, then workspace `beforeToolCall`, then the tool, then workspace `afterToolCall`, then agent `afterToolCall`.
+
 ## LSP inspection
 
 Enable `lsp` on a workspace to add semantic code inspection through language servers. This adds the `mastra_workspace_lsp_inspect` tool by default, which can return hover information, definition locations, and implementations for a symbol at a specific cursor position.

package/.docs/docs/workspace/sandbox.md

@@ -21,6 +21,7 @@ A sandbox provider executes commands in a controlled environment:
 - [`DaytonaSandbox`](https://mastra.ai/reference/workspace/daytona-sandbox): Executes commands in isolated Daytona cloud sandboxes
 - [`E2BSandbox`](https://mastra.ai/reference/workspace/e2b-sandbox): Executes commands in isolated E2B cloud sandboxes
 - [`ModalSandbox`](https://mastra.ai/reference/workspace/modal-sandbox): Executes commands in isolated Modal cloud sandboxes
+- [`RailwaySandbox`](https://mastra.ai/reference/workspace/railway-sandbox): Executes commands in ephemeral, isolated Railway cloud sandboxes
 
 ## Basic usage
 
@@ -107,13 +108,13 @@ const workspace = new Workspace({
 
 When the sandbox is a static instance, `workspace.init()` calls its `start()` method and `workspace.destroy()` calls its `destroy()` method. With a resolver, the workspace has no instance to manage at construction time — the caller owns the returned sandbox's lifecycle.
 
-The resolver must return a sandbox that is ready to use, either already started or able to handle calls without explicit startup. The caller also owns cleanup timing for returned sandboxes. Cleanup might happen per request, per tenant, per user, or as part of a long-lived sandbox pool; `workspace.destroy()` does not destroy resolver-returned sandboxes.
+The resolver must return a sandbox that's ready to use, either already started or able to handle calls without explicit startup. The caller also owns cleanup timing for returned sandboxes. Cleanup might happen per request, per tenant, per user, or as part of a long-lived sandbox pool; `workspace.destroy()` doesn't destroy resolver-returned sandboxes.
 
 > **Note:** `sandbox` resolvers are incompatible with `mounts` and `lsp: true`. Both require a concrete sandbox instance at construction time, so combining them with a resolver throws an `INVALID_CONFIG` error (for `mounts`) or disables LSP with a warning (for `lsp: true`).
 
 ### Tool registration
 
-With a static sandbox, the workspace inspects the instance to decide which tools to register. With a resolver, the workspace assumes full capabilities and registers `execute_command` (with `background` support), `get_process_output`, and `kill_process`. If the resolved sandbox does not implement a capability, the runtime throws a clear `SandboxFeatureNotSupportedError`.
+With a static sandbox, the workspace inspects the instance to decide which tools to register. With a resolver, the workspace assumes full capabilities and registers `execute_command` (with `background` support), `get_process_output`, and `kill_process`. If the resolved sandbox doesn't implement a capability, the runtime throws a clear `SandboxFeatureNotSupportedError`.
 
 ### Background process continuity
 
@@ -132,7 +133,7 @@ When a cached sandbox is no longer needed, destroy the sandbox in your own lifec
 
 ### Workspace instructions
 
-Workspace instructions describe the environment in the agent's system message. With a sandbox resolver, the workspace does not call the resolver to build these instructions. It emits stable placeholder text, so constructing the prompt never provisions a caller-owned sandbox and the system message stays consistent across requests, which keeps prompt caching effective.
+Workspace instructions describe the environment in the agent's system message. With a sandbox resolver, the workspace doesn't call the resolver to build these instructions. It emits stable placeholder text, so constructing the prompt never provisions a caller-owned sandbox and the system message stays consistent across requests, which keeps prompt caching effective.
 
 To include concrete per-request sandbox details, set `instructions.dynamicSandbox` to `'resolve'`:
 

package/.docs/guides/build-your-ui/ai-sdk-ui.md

@@ -395,7 +395,7 @@ Mastra streams data to the frontend as "parts" within messages. Each part has a
 | -------------------- | ----------------------- | ---------------------------------------------------------------------------------- |
 | `tool-{toolKey}`     | AI SDK built-in         | Tool invocation with states: `input-available`, `output-available`, `output-error` |
 | `data-workflow`      | `workflowRoute()`       | Workflow execution state snapshots with step status and final outputs              |
-| `data-workflow-step` | `workflowRoute()`       | Workflow step delta with the full payload for the step that just changed           |
+| `data-workflow-step` | `workflowRoute()`       | Workflow step delta with the full payload for the changed step                     |
 | `data-network`       | `networkRoute()`        | Agent network execution with ordered steps and outputs                             |
 | `data-tool-agent`    | Nested agent in tool    | Agent output streamed from within a tool's `execute()`                             |
 | `data-tool-workflow` | Nested workflow in tool | Workflow output streamed from within a tool's `execute()`                          |
@@ -508,7 +508,7 @@ export function Chat() {
 
 ### Rendering workflow data
 
-When using `workflowRoute()` or `handleWorkflowStream()`, Mastra emits `data-workflow` parts for workflow state snapshots and `data-workflow-step` parts for the full payload of the step that just changed. This keeps long-running workflows from repeating every completed step output in every intermediate snapshot.
+When using `workflowRoute()` or `handleWorkflowStream()`, Mastra emits `data-workflow` parts for workflow state snapshots and `data-workflow-step` parts for the full payload of the changed step. This keeps long-running workflows from repeating every completed step output in every intermediate snapshot.
 
 **Backend**:
 

package/.docs/guides/deployment/aws-bedrock-agentcore.md

@@ -1,6 +1,6 @@
 # Deploy Mastra to Amazon Bedrock AgentCore
 
-Deploy your Mastra application to [Amazon Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/) using the [AgentCore CLI](https://github.com/aws/agentcore-cli). The CLI scaffolds a bring-your-own-code (BYO) TypeScript project, builds the container with AWS CodeBuild, and provisions the runtime. A local Docker daemon is not required for deployment.
+Deploy your Mastra application to [Amazon Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/) using the [AgentCore CLI](https://github.com/aws/agentcore-cli). The CLI scaffolds a bring-your-own-code (BYO) TypeScript project, builds the container with AWS CodeBuild, and provisions the runtime. A local Docker daemon isn't required for deployment.
 
 This guide follows the [official AgentCore TypeScript walkthrough](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-cli-typescript.html) and adapts it to call a Mastra agent from the invocation handler.
 
@@ -190,7 +190,7 @@ export const weatherAgent = new Agent({
 
 > **Note:** `fromNodeProviderChain()` lets the agent pick up AWS credentials through the standard SDK resolution chain (environment variables, shared config files, SSO, and container or EC2 roles) instead of environment variables only.
 
-Replace the generated `src/mastra/index.ts` to remove the default file-based storage and observability config. AgentCore Runtime containers run as a non-root user with a read-only application directory, so the default `LibSQLStore` cannot open `./mastra.db` and the runtime fails at startup:
+Replace the generated `src/mastra/index.ts` to remove the default file-based storage and observability config. AgentCore Runtime containers run as a non-root user with a read-only application directory, so the default `LibSQLStore` can't open `./mastra.db` and the runtime fails at startup:
 
 ```ts
 import { Mastra } from '@mastra/core/mastra'
@@ -420,7 +420,7 @@ Run `agentcore status` to view the runtime ARN, endpoint, and recent invocations
 npx @aws/agentcore invoke "What is the weather in Tokyo?"
 ```
 
-To stream tokens as they are generated, use `--stream`:
+To stream tokens as they're generated, use `--stream`:
 
 ```bash
 npx @aws/agentcore invoke --stream "Plan a 3-day trip to Tokyo"

package/.docs/guides/deployment/inngest.md

@@ -93,7 +93,7 @@ export const inngest = new Inngest({
 })
 ```
 
-> **Warning:** Do not set `INNGEST_DEV` in production. It disables signature verification, which is required to securely receive events from Inngest Cloud.
+> **Warning:** Don't set `INNGEST_DEV` in production. It disables signature verification, which is required to securely receive events from Inngest Cloud.
 
 The `isDev` option on `new Inngest()` overrides `INNGEST_DEV` when both are set.
 
@@ -252,7 +252,7 @@ Before you begin, make sure you have:
 
 5. Sync with the [Inngest dashboard](https://app.inngest.com/env/production/apps) by selecting **Sync new app with Vercel** and following the instructions
 
-   > **Warning:** Inngest's auto-discover convention assumes `/api/inngest`. Because this guide uses `/inngest/api`, set the **URL** field on the Inngest app to your deployed origin plus `/inngest/api` (for example `https://your-app.vercel.app/inngest/api`). If you leave it on the default, the Inngest dashboard will not find your app's functions.
+   > **Warning:** Inngest's auto-discover convention assumes `/api/inngest`. Because this guide uses `/inngest/api`, set the **URL** field on the Inngest app to your deployed origin plus `/inngest/api` (for example `https://your-app.vercel.app/inngest/api`). If you leave it on the default, the Inngest dashboard won't find your app's functions.
 
 6. Invoke the workflow by going to **Functions**, selecting `workflow.increment-workflow`, selecting **All actions** > **Invoke**, and providing the following input:
 
@@ -433,9 +433,9 @@ The `createServe` function works with any Inngest adapter. See the [Inngest serv
 
 ## Running as a Connect worker
 
-`serve()` exposes an HTTP endpoint that Inngest calls into. As an alternative, `connect()` opens a long-lived outbound connection from your worker to Inngest, so the worker does not need a publicly reachable endpoint. Use this for long-running worker processes on runtimes such as Kubernetes, Docker, ECS, Fly.io, or Render.
+`serve()` exposes an HTTP endpoint that Inngest calls into. As an alternative, `connect()` opens a long-lived outbound connection from your worker to Inngest, so the worker doesn't need a publicly reachable endpoint. Use this for long-running worker processes on runtimes such as Kubernetes, Docker, ECS, Fly.io, or Render.
 
-> **Note:** Inngest Connect is in public beta. Serverless runtimes such as Vercel and AWS Lambda are not supported for Connect workers.
+> **Note:** Inngest Connect is in public beta. Serverless runtimes such as Vercel and AWS Lambda aren't supported for Connect workers.
 
 ### When to use `connect()` instead of `serve()`
 
@@ -453,7 +453,7 @@ Use the same Mastra workflow definitions with either `serve()` or `connect()`. T
 
 ### Setup
 
-Run the Mastra server and the Connect worker as two processes. The Mastra server in this setup does not need to expose `/inngest/api`:
+Run the Mastra server and the Connect worker as two processes. The Mastra server in this setup doesn't need to expose `/inngest/api`:
 
 ```ts
 import { Mastra } from '@mastra/core'

package/.docs/guides/deployment/temporal.md

@@ -155,7 +155,7 @@ const worker = await Worker.create({
 await worker.run()
 ```
 
-`MastraPlugin` rewrites the entry file into a workflow-only bundle and wires step handlers in as Temporal activities. You do not need to pass `activities` or `workflowsPath` to `Worker.create()` manually.
+`MastraPlugin` rewrites the entry file into a workflow-only bundle and wires step handlers in as Temporal activities. You don't need to pass `activities` or `workflowsPath` to `Worker.create()` manually.
 
 ## Running workflows
 
@@ -200,7 +200,7 @@ TEMPORAL_API_KEY=your-api-key
 
 See the [Temporal Cloud connection docs](https://docs.temporal.io/cloud/get-started) for mTLS and API key options.
 
-> **Warning:** The Temporal worker must run as a long-lived process. Do not deploy it to serverless platforms with short execution limits, such as AWS Lambda or Vercel functions. Use a container, VM, or worker-friendly platform such as Fly.io, Railway, or Kubernetes.
+> **Warning:** The Temporal worker must run as a long-lived process. Don't deploy it to serverless platforms with short execution limits, such as AWS Lambda or Vercel functions. Use a container, VM, or worker-friendly platform such as Fly.io, Railway, or Kubernetes.
 
 ## Configuration options
 
@@ -223,7 +223,7 @@ export const { createWorkflow, createStep } = init({
 ## Constraints and notes
 
 - Workflow ids must be static string literals. The build-time transformer reads the literal value to derive Temporal workflow export names.
-- Activities are generated automatically from `createStep()` handlers. Do not pass them in `Worker.create({ activities })`.
+- Activities are generated automatically from `createStep()` handlers. Don't pass them in `Worker.create({ activities })`.
 
 ## Related
 

package/.docs/guides/getting-started/nestjs.md

@@ -127,7 +127,7 @@ import { mastra } from './mastra'
 export class AppModule {}
 ```
 
-> **Note:** `MastraModule` registers a catch-all controller (`@All('*')`). If it is imported before your app modules, it can intercept unrelated routes and return 404s. To avoid conflicts, import `MastraModule` last or mount it under a dedicated prefix (e.g., `/api/v1/mastra`).
+> **Note:** `MastraModule` registers a catch-all controller (`@All('*')`). If it's imported before your app modules, it can intercept unrelated routes and return 404s. To avoid conflicts, import `MastraModule` last or mount it under a dedicated prefix (e.g., `/api/v1/mastra`).
 
 ## Test your agent
 

package/.docs/guides/migrations/mastra-cloud.md

@@ -56,7 +56,7 @@ The Mastra platform replaces Mastra Cloud with separate Studio and Server produc
 
 ## Replace Mastra Cloud Store with a hosted database
 
-Mastra Cloud provided a managed libSQL database, backed by [Turso](https://turso.tech). The Mastra platform does not host a database for you, so you need to point your storage at an externally hosted instance.
+Mastra Cloud provided a managed libSQL database, backed by [Turso](https://turso.tech). The Mastra platform doesn't host a database for you, so you need to point your storage at an externally hosted instance.
 
 If you were already using a hosted database ("bring your own"), no changes are needed. Ensure the connection string is set as an environment variable in the dashboard rather than hardcoded.
 
@@ -64,7 +64,7 @@ If you were using Cloud Store, follow the steps below to export your data and lo
 
 ### Export your Cloud Store data
 
-There are two ways to export your Cloud Store data: a one-click download from the dashboard, or a manual dump via the Turso CLI.
+You can export your Cloud Store data in two ways: download it from the dashboard, or create a manual dump with the Turso CLI.
 
 #### Option A — Export from the dashboard (recommended)
 
@@ -281,7 +281,7 @@ See [Studio deployment](https://mastra.ai/docs/studio/deployment) for details.
 
 ### Multiple environments
 
-Mastra platform projects do not have a built-in concept of named environments (for example `staging` vs `production`). To deploy the same codebase to multiple environments, create one project per environment and pair each deploy with the matching env file using `--env-file`.
+Mastra platform projects don't have a built-in concept of named environments (for example `staging` vs `production`). To deploy the same codebase to multiple environments, create one project per environment and pair each deploy with the matching env file using `--env-file`.
 
 The pattern below uses one `.env.<env>` file per environment, deploys to a project named `my-app-<env>`, and overrides `.mastra-project.json` per deploy with `MASTRA_ORG_ID` and `MASTRA_PROJECT_ID`:
 

package/.docs/guides/migrations/upgrade-to-v1/overview.md

@@ -8,7 +8,7 @@ This guide provides a comprehensive overview of breaking changes when upgrading
 
 > **Need help?:** Need help with the migration? Join our [Discord community](https://discord.gg/BTYqqHKUrf) to ask questions.
 
-> **Coming from Mastra Cloud?:** The legacy Mastra Cloud product has been replaced by the [Mastra platform](https://mastra.ai/docs/mastra-platform/overview), which splits hosting into two separate products: **Studio** (visual environment, observability) and **Server** (production API). Old Mastra Cloud access tokens do not work with Mastra platform — you must create new ones with `mastra auth tokens create`.
+> **Coming from Mastra Cloud?:** The legacy Mastra Cloud product has been replaced by the [Mastra platform](https://mastra.ai/docs/mastra-platform/overview), which splits hosting into two separate products: **Studio** (visual environment, observability) and **Server** (production API). Old Mastra Cloud access tokens don't work with Mastra platform — you must create new ones with `mastra auth tokens create`.
 >
 > If you upgrade to v1 packages without also migrating your `telemetry:` config to `observability:` and creating a Studio project, observability data will stop flowing. Follow the [Mastra Cloud migration guide](https://mastra.ai/guides/migrations/mastra-cloud) end to end.
 

package/.docs/guides/migrations/upgrade-to-v1/tracing.md

@@ -6,7 +6,7 @@ The observability system has been restructured in v1 with a dedicated `@mastra/o
 >
 > Complete this migration in the same change that bumps your Mastra packages, and verify traces appear in [Mastra Studio](https://mastra.ai/docs/studio/observability) before considering the upgrade complete. If you previously hosted on Mastra Cloud, also follow the [Mastra Cloud migration guide](https://mastra.ai/guides/migrations/mastra-cloud) — the new platform requires a new access token and a Studio project before `MastraPlatformExporter` can route data to it.
 
-> **Exporter rename:** `MastraPlatformExporter` (sends data to Mastra platform) replaces the previous `CloudExporter`, and `MastraStorageExporter` (persists data to Mastra Storage) replaces the previous `DefaultExporter`. The original classes still ship from `@mastra/observability` and behave identically, but they are deprecated. New code should use `MastraPlatformExporter` and `MastraStorageExporter`; existing imports of `CloudExporter`/`DefaultExporter` continue to work until they are removed in a future major version.
+> **Exporter rename:** `MastraPlatformExporter` (sends data to Mastra platform) replaces the previous `CloudExporter`, and `MastraStorageExporter` (persists data to Mastra Storage) replaces the previous `DefaultExporter`. The original classes still ship from `@mastra/observability` and behave identically, but they're deprecated. New code should use `MastraPlatformExporter` and `MastraStorageExporter`; existing imports of `CloudExporter`/`DefaultExporter` continue to work until they're removed in a future major version.
 
 ## Migration paths
 

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

@@ -116,7 +116,7 @@ for await (const chunk of result.fullStream) {
 }
 ```
 
-`resumeGenerate()` and `resumeStream()` are not supported and throw an error when called.
+`resumeGenerate()` and `resumeStream()` aren't supported and throw an error when called.
 
 ### Model management
 
@@ -160,7 +160,7 @@ With `persistSession: false`, `@mastra/acp` stops the ACP process after each pro
 
 ## Workspace integration
 
-ACP file operations go through Mastra's `Workspace` abstraction. If you do not pass `workspace`, `@mastra/acp` creates a `Workspace` backed by `LocalFilesystem` and uses `cwd` or `process.cwd()` as the filesystem base path.
+ACP file operations go through Mastra's `Workspace` abstraction. If you don't pass `workspace`, `@mastra/acp` creates a `Workspace` backed by `LocalFilesystem` and uses `cwd` or `process.cwd()` as the filesystem base path.
 
 Pass a custom `Workspace` when the ACP agent should read and write through a specific filesystem implementation:
 

package/.docs/reference/agents/agent.md

@@ -426,6 +426,12 @@ Returns an `AgentThreadSubscription` object with these members:
 
 **tools** (`ToolsInput | ({ requestContext: RequestContext }) => ToolsInput | Promise<ToolsInput>`): Tools that the agent can access. Can be provided statically or resolved dynamically.
 
+**hooks** (`ToolHooks`): Hooks that run before and after every tool call made by this agent. Per-execution hooks passed to \`generate()\` or \`stream()\` override matching hooks set here. See Tool hooks below.
+
+**hooks.beforeToolCall** (`(context: ToolHookContext) => void | ToolBeforeHookResult | Promise<void | ToolBeforeHookResult>`): Runs before a tool executes. Receives \`{ toolName, input, context, metadata }\`. Return \`{ proceed: false, output }\` to skip the tool call and use \`output\` as its result.
+
+**hooks.afterToolCall** (`(context: ToolAfterHookContext) => void | Promise<void>`): Runs after a tool executes. Receives \`{ toolName, input, context, metadata, output, error }\`. \`output\` is undefined when the tool throws, and \`error\` is set instead.
+
 **transform** (`ToolPayloadTransformPolicy`): Shared policy for transforming tool payloads before display streams or user-visible transcript messages receive them. Use per-tool \`transform\` on \`createTool()\` for tool-local rules.
 
 **workflows** (`Record<string, Workflow> | ({ requestContext: RequestContext }) => Record<string, Workflow> | Promise<Record<string, Workflow>>`): Workflows that the agent can execute. Can be static or dynamically resolved.
@@ -458,6 +464,44 @@ Returns an `AgentThreadSubscription` object with these members:
 
 **editor** (`false | { instructions?: boolean; tools?: boolean | { description?: boolean } }`): Controls which fields the editor can override for this code-defined agent. Omit to allow editing instructions and tools. See Editor overrides below.
 
+## Tool hooks
+
+Use `hooks` to run logic around every tool call the agent makes, including assigned tools, memory tools, toolsets, client tools, and workspace tools.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+export const agent = new Agent({
+  name: 'support-agent',
+  instructions: 'Help users with their questions.',
+  model: 'openai/gpt-5.5',
+  hooks: {
+    beforeToolCall: ({ toolName, input }) => {
+      console.log(`Running ${toolName}`, input)
+    },
+    afterToolCall: ({ toolName, output, error }) => {
+      console.log(`Finished ${toolName}`, { output, error })
+    },
+  },
+})
+```
+
+`beforeToolCall` can short-circuit the tool call by returning `{ proceed: false, output }`. The agent skips execution and uses `output` as the tool result:
+
+```typescript
+const result = await agent.generate('Clean up old records', {
+  hooks: {
+    beforeToolCall: ({ toolName }) => {
+      if (toolName === 'deleteRecord') {
+        return { proceed: false, output: { blocked: true } }
+      }
+    },
+  },
+})
+```
+
+The hook context `metadata` includes `agentId` and `agentName`. Per-execution hooks passed to `generate()` or `stream()` override matching agent-level hooks. When a [workspace](https://mastra.ai/reference/workspace/workspace-class) also defines `tools.hooks`, workspace hooks run inside the agent hook wrapper.
+
 ## Editor overrides
 
 When you register the [`MastraEditor`](https://mastra.ai/reference/editor/mastra-editor), the `editor` field controls which parts of a code-defined agent can be changed through the editor. Fields owned by code are read-only in Studio and are stripped from saved overrides.

package/.docs/reference/agents/channels.md

@@ -247,7 +247,7 @@ The `ResolveResourceIdContext` passed to the function:
 
 ## Inline media
 
-Controls which attachment types (images, video, PDFs, etc.) are sent as file parts to the model. Types that do not match are described as text summaries so the agent knows about the file without crashing models that reject unsupported types.
+Controls which attachment types (images, video, PDFs, etc.) are sent as file parts to the model. Types that don't match are described as text summaries so the agent knows about the file without crashing models that reject unsupported types.
 
 The default (`['image/png', 'image/jpeg', 'image/webp', 'application/pdf']`) matches the formats supported by major vision models. Override `inlineMedia` to expand the list (e.g. `['image/*', 'audio/*']`) or replace it entirely with a predicate function.
 

package/.docs/reference/agents/durable-agent.md

@@ -63,7 +63,7 @@ Returns: `DurableAgent`
 
 ## `createEventedAgent(options)`
 
-Wraps an `Agent` with fire-and-forget durable execution on the built-in workflow engine. Like `createDurableAgent`, it returns a result you stream from, but the underlying workflow runs non-blocking (via `startAsync`) instead of running to completion before the stream is wired up. Use it when you want the run to progress independently of the caller. It does not accept `id` or `name` overrides.
+Wraps an `Agent` with fire-and-forget durable execution on the built-in workflow engine. Like `createDurableAgent`, it returns a result you stream from, but the underlying workflow runs non-blocking (via `startAsync`) instead of running to completion before the stream is wired up. Use it when you want the run to progress independently of the caller. It doesn't accept `id` or `name` overrides.
 
 ```typescript
 import { createEventedAgent } from '@mastra/core/agent/durable'
@@ -151,7 +151,7 @@ await output.text
 
 Returns: `Promise<DurableAgentStreamResult>`
 
-> **Warning:** The `cleanup()` returned by `observe()` destroys the run's registry entries and cached events. Only call it when you are done with the run. If the run is suspended and you intend to resume later, do not call `cleanup()` — let the auto-cleanup timer handle it after the run finishes or errors. Auto-cleanup does not fire on suspended events.
+> **Warning:** The `cleanup()` returned by `observe()` destroys the run's registry entries and cached events. Only call it when you are done with the run. If the run is suspended and you intend to resume later, don't call `cleanup()` — let the auto-cleanup timer handle it after the run finishes or errors. Auto-cleanup doesn't fire on suspended events.
 
 ## Stream options
 

package/.docs/reference/agents/generate.md

@@ -266,6 +266,8 @@ const response = await agent.generate('Help me organize my day', {
 
 **options.clientTools** (`ToolsInput`): Client-side tools available during execution.
 
+**options.hooks** (`ToolHooks`): Per-execution hooks that run before and after tool calls. Overrides matching agent-level hooks for this execution. \`beforeToolCall\` can return \`{ proceed: false, output }\` to skip the tool call.
+
 **options.savePerStep** (`boolean`): Save messages incrementally after each generation step completes (default: false). Disabled internally when observational memory is enabled.
 
 **options.providerOptions** (`Record<string, Record<string, JSONValue>>`): Provider-specific options passed to the language model.

package/.docs/reference/agents/generateLegacy.md

@@ -84,6 +84,8 @@ await agent.generateLegacy('message for agent')
 
 **options.clientTools** (`ToolsInput`): Tools that are executed on the 'client' side of the request. These tools do not have execute functions in the definition.
 
+**options.hooks** (`ToolHooks`): Per-execution hooks that run before and after tool calls. Overrides matching agent-level hooks for this execution. \`beforeToolCall\` can return \`{ proceed: false, output }\` to skip the tool call.
+
 **options.savePerStep** (`boolean`): Save messages incrementally after each generation step completes (default: false). Disabled internally when observational memory is enabled.
 
 **options.providerOptions** (`Record<string, Record<string, JSONValue>>`): Additional provider-specific options that are passed through to the underlying LLM provider. The structure is \`{ providerName: { optionKey: value } }\`. Since Mastra extends AI SDK, see the \[AI SDK documentation]\(https\://sdk.vercel.ai/docs/providers/ai-sdk-providers) for complete provider options.

package/.docs/reference/ai-sdk/handle-chat-stream.md

@@ -21,7 +21,7 @@ When you pass `structuredOutput` to the underlying agent execution, the final st
 }
 ```
 
-The `object` field contains your full structured output value. Mastra emits this event for the final structured output object only. Partial structured output chunks are not exposed in the UI stream.
+The `object` field contains your full structured output value. Mastra emits this event for the final structured output object only. Partial structured output chunks aren't exposed in the UI stream.
 
 Read this event with AI SDK UI's custom data handling, such as `onData`, or render it from message data parts.