@mastra/mcp-docs-server 1.2.13 → 1.2.14-alpha.3

package/.docs/docs/agent-controller/modes.md

@@ -1,147 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Modes
-
-Modes define the different behaviors an AgentController can run. Each mode layers its own instructions and tool overrides on top of a shared backing agent, so the same agent can act as a planner in one mode and an executor in another. The AgentController keeps exactly one mode active at a time and carries the thread and state across switches, plus handles the transition between them.
-
-Every AgentController needs at least one mode, the `modes` array is required, and the AgentController throws at construction if it's empty. A single-purpose AgentController still defines one mode. Multiple modes are how you give a session more than one behavior to switch between.
-
-A mode supplies three things that change how the agent behaves:
-
-- **Instructions**: layered on top of the backing agent's own instructions while the mode is active.
-- **Tools**: either replacing or adding to the backing agent's tools (see [Mode tool overrides](#mode-tool-overrides)).
-- **Model**: an optional `defaultModelId` to bootstrap model selection when the session enters the mode.
-
-Because every mode shares the same backing agent, thread, and state, switching modes changes how the agent behaves without losing conversation context.
-
-## Quickstart
-
-Import the `AgentController` class and create a new instance with your agent and modes:
-
-```typescript
-import { AgentController } from '@mastra/core/agent-controller'
-import { myAgent } from './agents'
-
-const agentController = new AgentController({
-  id: 'multi-mode',
-  agent: myAgent,
-  modes: [
-    {
-      id: 'plan',
-      name: 'Plan',
-      metadata: { default: true },
-      instructions: 'Reason about the task before making changes.',
-    },
-    { id: 'build', name: 'Build', instructions: 'Implement the approved plan.' },
-  ],
-})
-
-await agentController.init()
-```
-
-## Defining modes
-
-Each mode requires an `id`. When a top-level `agent` is provided, modes layer instructions and tool overrides on the shared agent. Each mode can also specify a `defaultModelId` to bootstrap model selection:
-
-```typescript
-import { AgentController } from '@mastra/core/agent-controller'
-
-const agentController = new AgentController({
-  id: 'multi-mode',
-  agent: myAgent,
-  modes: [
-    {
-      id: 'plan',
-      name: 'Plan',
-      metadata: { default: true },
-      defaultModelId: 'anthropic/claude-sonnet-4-6',
-      instructions: 'Reason about the task before making changes.',
-    },
-    {
-      id: 'build',
-      name: 'Build',
-      defaultModelId: 'anthropic/claude-sonnet-4-6',
-      instructions: 'Implement the approved plan.',
-    },
-  ],
-})
-```
-
-### Mode tool overrides
-
-Modes support two strategies for tool configuration. Use `tools` to replace the backing agent's tools entirely, or `additionalTools` to layer extra tools on top:
-
-```typescript
-// Replace — agent sees only these tools in plan mode
-const planMode = { id: 'plan', tools: { planTool } }
-
-// Augment — agent keeps its own tools plus these
-const buildMode = { id: 'build', additionalTools: { deployTool } }
-```
-
-You can't set both `tools` and `additionalTools` on the same mode.
-
-### Restricting tool visibility
-
-`tools` and `additionalTools` control which tools are **added** to a mode's run, they don't hide the backing agent's own tools. To restrict which of those tools the model can actually see and call, set `availableTools`:
-
-```typescript
-const reviewMode = {
-  id: 'review',
-  name: 'Review',
-  // Only these tools are visible to the model in this mode.
-  availableTools: ['view', 'find_files', 'search_content'],
-}
-```
-
-`availableTools` is a per-mode visibility allowlist that matches each tool by its final exposed name:
-
-- **`undefined`** (default): no mode-level restriction: every tool is visible.
-- **`[]`**: no tools are available for this mode.
-- A denied tool stays hidden even when the list includes it. Per-tool and per-category `deny` rules in your permission config always take precedence.
-
-Workspace tools use the same list as every other tool, reference them by their exposed names (`view`, `write_file`, `find_files`, etc.). Visibility is enforced at LLM-call time, so the model never sees, and can't attempt to call, a tool outside the allowlist.
-
-### Mode transitions
-
-A mode can declare a `transitionsTo` target. When the `submit_plan` built-in tool runs in that mode, the AgentController transitions to the target mode on approval:
-
-```typescript
-const planMode = {
-  id: 'plan',
-  name: 'Plan',
-  transitionsTo: 'build',
-  instructions: 'Reason about the task and submit a plan.',
-}
-```
-
-On plan approval, the AgentController automatically switches to `build` mode. On rejection, the agent remains in `plan` mode to revise.
-
-## Switching modes
-
-The active mode lives on the Session, so call `agentController.session.mode.switch()` to change it. The switch aborts any in-progress generation and saves the current model to the outgoing mode, plus emits a `mode_changed` event. It then resolves the incoming mode's model and, when one resolves, applies it and emits a `model_changed` event:
-
-```typescript
-await agentController.session.mode.switch({ modeId: 'build' })
-```
-
-## Querying modes
-
-The AgentController exposes the full mode catalog, while the Session tracks which mode is active. Use `agentController.listModes()` to read every configured mode, `agentController.session.mode.get()` for the active mode ID, and `agentController.session.mode.resolve()` for the active mode's full definition:
-
-```typescript
-// List all configured modes
-const modes = agentController.listModes()
-
-// Get the current mode ID
-const modeId = agentController.session.mode.get()
-
-// Get the full mode object
-const mode = agentController.session.mode.resolve()
-```
-
-## Related
-
-- [AgentController overview](https://mastra.ai/docs/agent-controller/overview)
-- [Threads and state](https://mastra.ai/docs/agent-controller/threads-and-state)
-- [API reference](https://mastra.ai/reference/agent-controller/agent-controller-class)

package/.docs/docs/agent-controller/overview.md

@@ -1,136 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# AgentController overview
-
-> **Beta:** The `AgentController` feature is in beta stage and subject to breaking changes in minor versions until it graduates from its beta status.
-
-The AgentController is a session controller for building interactive agent applications.
-
-It handles the runtime concerns between your UI and the agent loop. These include conversation threads, mode switches, and persistent state. It also gates tool execution with approvals and coordinates subagents. You can focus on what your agent does rather than how to wire it together.
-
-An AgentController exposes a [`Session`](https://mastra.ai/docs/agent-controller/session), the per-conversation runtime state that tracks the active mode, model, thread binding, permission grants, follow-up queue, and token usage. The AgentController is the shared host. The Session is the conversation running inside it. In a multi-user host, the same AgentController can back many Sessions at once.
-
-[Mastra Code](https://code.mastra.ai/) is the flagship AgentController implementation. It's a terminal-based coding agent with multi-model support, persistent conversations, and plan-then-execute workflows.
-
-## What you can build
-
-The AgentController gives you the runtime pieces to release interactive agent applications. Each outcome below maps to a capability you can use today:
-
-- **Resume a conversation exactly where the user left off.** Persistent [threads and state](https://mastra.ai/docs/agent-controller/threads-and-state) reload the active mode, model, and progress across restarts, so a coding agent or assistant picks up mid-task instead of starting over.
-- **Gate destructive actions behind human approval.** [Tool approvals and permission policies](https://mastra.ai/docs/agent-controller/tool-approvals) let you require confirmation for risky operations like file writes or deployments, while trusted tools run automatically.
-- **Move a task through distinct phases without losing context.** [Modes](https://mastra.ai/docs/agent-controller/modes) switch the agent's instructions, tools, and model on the same thread, so you can build a plan-then-execute coding agent or a research-then-draft assistant.
-- **Let users pick the right model for each step.** Per-mode [model management](https://mastra.ai/reference/agent-controller/agent-controller-class) switches models at runtime and tracks usage, which powers copilot UIs where users trade speed for capability.
-- **Delegate focused work to child agents.** [Subagents](https://mastra.ai/docs/agent-controller/subagents) run subtasks with constrained tools and can fork the parent conversation, so a research mode can spin off web search or code review without polluting the main thread.
-- **Drive a live UI from agent activity.** The [event system](https://mastra.ai/docs/agent-controller/session) emits typed events and coalesced display snapshots, so your TUI or web app reflects message updates, mode changes, and pending approvals in real time.
-- **Run long-lived autonomous agents.** Structured task lists, interval handlers, and observational memory keep background task runners on track and let them learn across threads.
-
-## When to use the AgentController
-
-Use the AgentController when your application needs:
-
-- Multiple agent modes that share one conversation thread (e.g., plan → build → review)
-- A control layer between your UI and the agent loop (model switching, state persistence, thread management)
-- Tool approval flows and permission policies for human-in-the-loop gating
-- Subagent orchestration to delegate focused subtasks with constrained tools
-- Session continuity with persistent threads, state, and observational memory across restarts
-
-You could assemble all of this yourself on top of the [Agent class](https://mastra.ai/docs/agents/overview), which exposes the full agent loop, tools, and memory. The AgentController provides opinionated defaults for an ongoing session where the agent acts as a collaborator rather than a one-shot endpoint. Reach for the Agent class directly when you want full control or a request-response call. Reach for the AgentController when you want the collaborative-session model without building the runtime around it.
-
-## Key capabilities
-
-- **Session**: Per-conversation state: active thread, mode, model, grants, follow-ups, token usage, and the display snapshot: accessed through `agentController.session`. See [Session](https://mastra.ai/docs/agent-controller/session).
-- **Modes**: Define distinct agent personalities (instructions, tools, model) and switch between them without losing conversation context. See [Modes](https://mastra.ai/docs/agent-controller/modes).
-- **Threads and state**: Persist conversations and structured state across sessions, users, and mode switches. See [Threads and state](https://mastra.ai/docs/agent-controller/threads-and-state).
-- **Subagents**: Spawn focused child agents with constrained tools for subtasks, optionally forking the parent conversation. See [Subagents](https://mastra.ai/docs/agent-controller/subagents).
-- **Tool approvals and permissions**: Configure which tools require user confirmation and grant session-wide exceptions, plus handle interactive tool suspension. See [Tool approvals](https://mastra.ai/docs/agent-controller/tool-approvals).
-- **Model management**: Switch models per-mode at runtime, track usage, and resolve gateway-backed models through Mastra's [model router](https://mastra.ai/models).
-- **Follow-ups and steering**: Queue messages while the agent is running, or inject mid-stream instructions to redirect the agent. Built on [signals](https://mastra.ai/docs/long-running-agents/signals).
-- **Event system**: Subscribe to typed events (message updates, mode changes, tool approvals) or coalesced `AgentControllerDisplayState` snapshots to drive your UI. See [Events](https://mastra.ai/reference/agent-controller/agent-controller-class).
-- **Observational memory**: Automatic summarization and reflection across threads for long-running agent sessions. See [Observational memory](https://mastra.ai/docs/memory/observational-memory).
-
-## Quickstart
-
-Import the `AgentController` class and create a new instance with an agent, storage backend, and modes:
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { AgentController } from '@mastra/core/agent-controller'
-import { LibSQLStore } from '@mastra/libsql'
-
-const agent = new Agent({
-  id: 'assistant',
-  name: 'assistant',
-  instructions: 'Help the user plan and complete tasks.',
-  model: 'openai/gpt-5.6-sol',
-})
-
-const agentController = new AgentController({
-  id: 'my-agent',
-  agent,
-  storage: new LibSQLStore({ id: 'agent-storage', url: 'file:./data.db' }),
-  modes: [
-    {
-      id: 'plan',
-      name: 'Plan',
-      metadata: { default: true },
-      instructions: 'Reason about changes before making them.',
-    },
-    { id: 'build', name: 'Build', instructions: 'Implement the approved plan.' },
-  ],
-})
-
-agentController.subscribe(event => {
-  if (event.type === 'message_update') {
-    console.log(event.message)
-  }
-})
-
-await agentController.init()
-await agentController.selectOrCreateThread()
-await agentController.sendMessage({ content: 'Hello!' })
-```
-
-Visit the [AgentController reference](https://mastra.ai/reference/agent-controller/agent-controller-class) for the full constructor parameters and method signatures.
-
-## Architecture
-
-The AgentController sits between your application layer and the underlying agent loop:
-
-```text
-┌───────────────────────────────────────┐
-│         Your App (TUI/Web/API)        │
-└───────────────────────────────────────┘
-      │  commands              ▲  events
-      ▼                        │
-┌───────────────────────────────────────┐
-│            AgentController             │
-│ Config · storage · threads            │
-│ permissions · subagents · events      │
-│                                       │
-│  ┌─────────────────────────────────┐  │
-│  │     agentController.session     │  │
-│  │ identity · thread · mode        │  │
-│  │ model · run · grants            │  │
-│  │ display state                   │  │
-│  └─────────────────────────────────┘  │
-└───────────────────────────────────────┘
-                   │
-                   ▼
-┌───────────────────────────────────────┐
-│         Agent + Memory + Tools        │
-└───────────────────────────────────────┘
-```
-
-Your app sends commands, send a message, switch mode, approve a tool call, and receives typed events such as `message_update` and `tool_approval_required`.
-
-The AgentController manages the lifecycle internally. It persists threads and routes requests to the correct mode agent. It also enforces permissions and emits events as state changes.
-
-## Next steps
-
-- [Session](https://mastra.ai/docs/agent-controller/session): The per-conversation state on an AgentController
-- [Modes](https://mastra.ai/docs/agent-controller/modes): Define and switch between agent personalities
-- [Threads and state](https://mastra.ai/docs/agent-controller/threads-and-state): Manage persistent conversations
-- [Subagents](https://mastra.ai/docs/agent-controller/subagents): Delegate focused subtasks
-- [Tool approvals and permissions](https://mastra.ai/docs/agent-controller/tool-approvals): Human-in-the-loop gating
-- [API reference](https://mastra.ai/reference/agent-controller/agent-controller-class): Full constructor and method docs
-- 📹 [Mastra AgentController harness workshop](https://www.youtube.com/watch?v=tV1pSleP-LM)

package/.docs/docs/agent-controller/session.md

@@ -1,161 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Session
-
-A [`Session`](https://mastra.ai/reference/agent-controller/session) holds the live state of an AgentController. It identifies the user and active thread, along with the selected mode and model. It also stores permission grants, queued follow-ups, token usage, application state, and the display snapshot.
-
-You reach it through `agentController.session`.
-
-## What the Session tracks
-
-The Session is the live state of a single user's interaction with the AgentController.
-
-It answers who owns the session and which thread is bound. It also identifies the selected mode and model while tracking approvals, queued or running work, application state, and the snapshot to render.
-
-A session has one active thread at a time but can list, switch between, and clone many threads over its lifetime. Anything that describes the current state lives here. The AgentController owns the shared infrastructure every session runs on.
-
-Each session has its own identity and state. One AgentController can therefore serve many users at once, with a separate `resourceId` and Session preventing mode, grant, or active-thread data from leaking between users.
-
-Calling `createSession` with the same `resourceId` returns the existing session (get-or-create), so a resource always resumes its own session.
-
-The rest of this page walks through the Session's state. Each part is a focused sub-object on `agentController.session`:
-
-- **Who and where**: [Identity](#identity) sets the stable session `id`, `ownerId`, and resource the session belongs to, and [Thread](#thread) tracks the currently bound thread.
-- **How the agent behaves**: [Mode and model](#mode-and-model) controls which agent profile and model are active, and [Permission grants](#permission-grants) records what the user has approved to run without prompting.
-- **What's happening right now**: [Run state](#run-state) reflects the in-flight generation, and [Follow-ups](#follow-ups) holds messages queued to send when it finishes.
-- **What you store and render**: [State](#state) holds your application's structured data, and [Display state](#display-state) is the single snapshot your UI renders from.
-
-The AgentController performs actions that change this state, switching threads, modes, or models, because those operations coordinate shared infrastructure and emit events. The Session is where you read the result. The sections below note this split where it matters.
-
-## Identity
-
-`session.identity` holds three stable identifiers for the conversation: a session `id`, an `ownerId`, and the resource ID. Threads are scoped to a resource ID, so this is what groups a conversation's threads together:
-
-```typescript
-const sessionId = agentController.session.identity.getId()
-const ownerId = agentController.session.identity.getOwnerId()
-const resourceId = agentController.session.identity.getResourceId()
-const threadId = agentController.session.thread.getId()
-```
-
-The session `id` and `ownerId` are stable for the life of the session, they don't change when the resource ID is switched. They mirror the `id` and `ownerId` fields on `SessionRecord` in storage, so storage layers can key sessions by a stable identifier rather than the mutable resource ID.
-
-The resource ID is set when creating a session via [`agentController.createSession()`](https://mastra.ai/reference/agent-controller/agent-controller-class) and defaults to the agentController `id`. See [Resource IDs](https://mastra.ai/docs/agent-controller/threads-and-state) for how it scopes threads.
-
-## Thread
-
-`session.thread` owns the active thread binding and read access to threads and messages. The AgentController performs lifecycle transitions; the Session reads the result:
-
-```typescript
-// Lifecycle transitions live on the AgentController
-await agentController.switchThread({ threadId: 'thread-abc123' })
-
-// Reads live on the Session
-const threads = await agentController.session.thread.list()
-const messages = await agentController.session.thread.listActiveMessages()
-```
-
-See [Threads and state](https://mastra.ai/docs/agent-controller/threads-and-state) for the full lifecycle.
-
-## Mode and model
-
-The AgentController defines the available modes in `config.modes`. The Session tracks which mode and model are _currently_ selected:
-
-```typescript
-// Switch mode (aborts the run, emits events)
-await agentController.session.mode.switch({ modeId: 'build' })
-
-// Read the current selection (Session state)
-const modeId = agentController.session.mode.get()
-const mode = agentController.session.mode.resolve()
-const modelId = agentController.session.model.get()
-```
-
-See [Modes](https://mastra.ai/docs/agent-controller/modes) for how modes carry their own model.
-
-## Permission grants
-
-The AgentController owns permission _policy_, which categories or tools require approval. The Session owns the _grants_ a user makes during the conversation. A grant lets a tool run for the rest of the session without prompting again:
-
-```typescript
-// Grant a category or tool for the rest of the session
-agentController.session.grantCategory('edit')
-agentController.session.grantTool('mastra_workspace_execute_command')
-
-// Inspect current grants
-const grants = agentController.session.getGrants()
-```
-
-Grants are intentionally in-memory and reset when the session restarts. See [Tool approvals](https://mastra.ai/docs/agent-controller/tool-approvals) for the approval flow.
-
-## Run state
-
-`session.run` tracks the in-flight generation: whether a run is active, its run and trace IDs, and the abort signal. Use it to reflect run status in your UI:
-
-```typescript
-if (agentController.session.run.isRunning()) {
-  // show a stop button
-}
-
-// Abort the active run (AgentController orchestration clears related state)
-agentController.abort()
-```
-
-## Follow-ups
-
-A user may want to add to the conversation while the agent is still working. Instead of dropping or interrupting those messages, the Session queues them on `session.followUps` and sends them when the current run finishes:
-
-```typescript
-const queued = agentController.session.followUps.count()
-```
-
-Queue a follow-up with `agentController.followUp({ content })`. To redirect the agent mid-run instead of waiting, use `agentController.steer({ content })`. Both build on [signals](https://mastra.ai/docs/long-running-agents/signals).
-
-## State
-
-`session.state` holds the conversation's application state, structured values that agents and the UI share, such as model preferences, feature flags, or progress.
-
-The AgentController defines the shape with a `stateSchema`. The Session owns the live snapshot and validates updates against that schema. Every write emits `state_changed`:
-
-```typescript
-const state = agentController.session.state.get()
-await agentController.session.state.set({ theme: 'light' })
-```
-
-See [Threads and state](https://mastra.ai/docs/agent-controller/threads-and-state) for defining a schema.
-
-## Display state
-
-A conversation emits fine-grained events for streamed tokens and tool activity. Other events cover pending approvals, task updates, and token usage.
-
-Subscribing to each event type and reassembling the current picture yourself is tedious and error-prone.
-
-`session.displayState` does that work for you.
-
-It's a reducer-maintained snapshot.
-
-The Session keeps one `AgentControllerDisplayState` object and folds every agentController event into it as it happens, so the snapshot always reflects the latest state.
-
-It captures everything a UI needs to render. The snapshot shows whether the agent is running, what it's streaming, and which tools or subagents are active. It also includes pending approvals, the current task list, token usage, and queued follow-ups.
-
-Because it's a single object, you can drive an entire UI from one place: read the current snapshot with `get()`, and re-render whenever the AgentController emits `display_state_changed` (fired after every other event):
-
-```typescript
-const snapshot = agentController.session.displayState.get()
-
-// Re-render from the snapshot on every change
-agentController.subscribe(event => {
-  if (event.type === 'display_state_changed') {
-    render(agentController.session.displayState.get())
-  }
-})
-```
-
-This is the recommended pattern for most UIs. Subscribe to individual typed events only when you need to react to a specific transition rather than re-render the whole view. Visit the [Session reference](https://mastra.ai/reference/agent-controller/session) for the full list of sub-objects and method signatures.
-
-## Related
-
-- [AgentController overview](https://mastra.ai/docs/agent-controller/overview)
-- [Threads and state](https://mastra.ai/docs/agent-controller/threads-and-state)
-- [Tool approvals](https://mastra.ai/docs/agent-controller/tool-approvals)
-- [Session reference](https://mastra.ai/reference/agent-controller/session)

package/.docs/docs/agent-controller/subagents.md

@@ -1,110 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Subagents
-
-Subagents let a parent agent delegate focused tasks to child agents with constrained tools and instructions. The AgentController auto-generates a `subagent` built-in tool that the parent model can call to spawn any configured subagent type. Reach for a subagent when a task needs a different toolset or instruction set than the parent agent, when you want to isolate a subtask's messages from the parent thread, or when the parent should delegate to a cheaper or faster model for specific work.
-
-## Quickstart
-
-Define subagent types in the AgentController constructor:
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { AgentController } from '@mastra/core/agent-controller'
-
-const agent = new Agent({
-  id: 'assistant',
-  name: 'assistant',
-  instructions: 'Use subagents when a focused task needs a narrower toolset.',
-  model: 'openai/gpt-5.6-sol',
-})
-
-const agentController = new AgentController({
-  id: 'with-subagents',
-  agent,
-  modes: [{ id: 'default', name: 'Default', metadata: { default: true } }],
-  subagents: [
-    {
-      id: 'explore',
-      name: 'Explore',
-      description: 'Reads files and gathers context without making changes.',
-      instructions: 'You are a read-only exploration agent.',
-      allowedWorkspaceTools: ['read_file', 'list_directory', 'grep_search'],
-      defaultModelId: 'anthropic/claude-haiku-4-5',
-      maxSteps: 30,
-    },
-    {
-      id: 'execute',
-      name: 'Execute',
-      description: 'Makes changes to files and runs commands.',
-      instructions: 'You are an execution agent.',
-      allowedWorkspaceTools: ['read_file', 'write_file', 'execute_command'],
-      defaultModelId: 'anthropic/claude-sonnet-4-6',
-    },
-  ],
-})
-```
-
-The parent agent can then call the auto-generated `subagent` tool with a `task` description and optional `agentType`.
-
-When you define a subagent, give its `description` and `instructions` a clear, narrow scope. The `description` is what the parent model reads to decide _when_ to delegate, so state the single job the subagent is for and, by implication, what it's not for, "Reads files and gathers context without making changes" tells the parent to reach for it during exploration and to handle edits elsewhere. The `instructions` then keep the child agent inside that job. A subagent scoped to one task with a focused toolset stays predictable and is easier for the parent to route to. A broadly described subagent invites the parent to over-delegate and blurs the boundary between types. Pair the narrow scope with `allowedWorkspaceTools` so the subagent can only do what its description promises.
-
-For the full list of subagent configuration options, see [`AgentController` reference](https://mastra.ai/reference/agent-controller/agent-controller-class).
-
-## Forked subagents
-
-A default subagent starts with a fresh context: it can't see the parent conversation, so you pass everything it needs in the `task` description. That's the right model for self-contained work, but it has two costs. The subagent has no access to what's already happened, and it builds a brand-new request prefix, a different system prompt and tool schemas, so it can't reuse the parent's prompt cache.
-
-**Forked subagents** solve both. Instead of a fresh agent, a fork clones the parent thread and runs the parent agent itself, so it sees the full conversation history and keeps the same system prompt and tool schemas as the parent. The identical prefix means the model's prompt cache still hits, which makes context-heavy delegation cheaper and faster.
-
-Use a fork when the subtask depends on the conversation so far, prior messages, earlier tool results, or the parent's tool environment, and you want to run it without paying to rebuild that context. Use a default subagent when the task is self-contained and benefits from a narrower toolset or a tighter system prompt, or alternatively a cheaper model.
-
-Enable forked mode per-type:
-
-```typescript
-const collaborator = {
-  id: 'collaborator',
-  name: 'Collaborator',
-  description: 'Continues the conversation in a fork.',
-  forked: true,
-}
-```
-
-Or per-invocation via the `subagent` tool's `forked` input parameter, which overrides the type's default.
-
-### Forked mode semantics
-
-Because a fork reuses the parent agent to keep the prompt prefix stable, the subagent's own definition is mostly set aside:
-
-- Memory must be configured on the AgentController, since forking clones the parent thread.
-
-Without it, the fork call returns an error.
-
-- The fork runs with the parent agent's instructions, tools, and model. The subagent definition's own `instructions`, `tools`, and `defaultModelId` are ignored, and a per-invocation `modelId` is ignored too.
-- Only the subagent definition's `description` still matters: it's what the parent model reads to decide when to delegate.
-- Fork threads are tagged with `metadata.forkedSubagent === true` and hidden from `session.thread.list()` by default.
-- Recursive forks are blocked at runtime: the inherited `subagent` tool is disabled inside a fork to prevent infinite nesting.
-
-## Subagent model management
-
-Set a global or per-type subagent model at runtime:
-
-```typescript
-// Global subagent model
-await agentController.session.subagents.model.set({ modelId: 'anthropic/claude-sonnet-4-6' })
-
-// Per-type override
-await agentController.session.subagents.model.set({
-  modelId: 'anthropic/claude-haiku-4-5',
-  agentType: 'explore',
-})
-
-// Read current model
-const modelId = agentController.session.subagents.model.get({ agentType: 'explore' })
-```
-
-## Related
-
-- [AgentController overview](https://mastra.ai/docs/agent-controller/overview)
-- [Tool approvals and permissions](https://mastra.ai/docs/agent-controller/tool-approvals)
-- [API reference](https://mastra.ai/reference/agent-controller/agent-controller-class)