@mastra/acp 0.2.0-alpha.1 → 0.2.1-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @mastra/acp
 
+## 0.2.1-alpha.0
+
+### Patch Changes
+
+- Fixed ACP tools to keep their default session alive across executions. ([#17516](https://github.com/mastra-ai/mastra/pull/17516))
+
+- Updated dependencies [[`f82cc72`](https://github.com/mastra-ai/mastra/commit/f82cc72edca0ce636fe18abaf2598d89a0c6bcca), [`fcf6027`](https://github.com/mastra-ai/mastra/commit/fcf602747f6771731dda268ff3493b836f9f0ee9)]:
+  - @mastra/core@1.41.0-alpha.0
+
+## 0.2.0
+
+### Minor Changes
+
+- Added programmatic model selection for ACP agents using the `model` option. ([#17010](https://github.com/mastra-ai/mastra/pull/17010))
+
+  You can now set the model directly when creating `AcpAgent` or `createACPTool`, instead of relying on environment variables.
+
+  ```ts
+  const codeAgent = new AcpAgent({
+    id: 'code-agent',
+    description: 'ACP-compatible coding agent',
+    command: 'claude',
+    args: ['--acp'],
+    model: 'claude-sonnet-4-20250514',
+  });
+  ```
+
+  Discover available models with `getAvailableModels()` and change the model at runtime with `setModel()`. Invalid model IDs throw a descriptive error listing valid options.
+
+### Patch Changes
+
+- Removed zod as a required peer dependency. Internal schemas now use plain JSON Schema objects instead of zod runtime. ([#16726](https://github.com/mastra-ai/mastra/pull/16726))
+
+- Updated dependencies [[`cfa2e3a`](https://github.com/mastra-ai/mastra/commit/cfa2e3a5292322f48bb28b4d257d631da7f9d3cc), [`0cbece9`](https://github.com/mastra-ai/mastra/commit/0cbece9d832cb134a74cdbf3682d390a058215a4), [`2f5f58a`](https://github.com/mastra-ai/mastra/commit/2f5f58a9a8bb13bcdc6789db221eef7c9bf1ff02), [`7dfe1bc`](https://github.com/mastra-ai/mastra/commit/7dfe1bcfe71d261a6fd6bbf29b1dec49d78fb98f), [`ac442a4`](https://github.com/mastra-ai/mastra/commit/ac442a42fda0354ac2bcea772bf6691cb3e9dbb3), [`b7286f4`](https://github.com/mastra-ai/mastra/commit/b7286f4308267f5fd70e6bfee10dba9472640906), [`6096445`](https://github.com/mastra-ai/mastra/commit/60964459733f0ab384584d95e19c36607ffdf7b0), [`d72dc4b`](https://github.com/mastra-ai/mastra/commit/d72dc4b12d832546c05c20255fa96fe4eb515900), [`a481027`](https://github.com/mastra-ai/mastra/commit/a481027b549ba1018414990c8f045eaee7b9f413), [`1e5c067`](https://github.com/mastra-ai/mastra/commit/1e5c067d2e20a781af670578180d1ee249806d41), [`168fa09`](https://github.com/mastra-ai/mastra/commit/168fa09d6b39114cb8c13bd06f1dccb9bc81c6cd), [`df1947a`](https://github.com/mastra-ai/mastra/commit/df1947affa40f742067542251fac7ca759492ef4), [`ee59b74`](https://github.com/mastra-ai/mastra/commit/ee59b743ce73ad11784b4d9c6fbba8568edee1c8), [`a97b1a0`](https://github.com/mastra-ai/mastra/commit/a97b1a0abaed83946c3519d1e0f680d0815b8a67), [`008baaf`](https://github.com/mastra-ai/mastra/commit/008baafd8d851f831407045aebead5a2e3342eff), [`801baa0`](https://github.com/mastra-ai/mastra/commit/801baa07cccdbaec1d00942a92bdc831111744a2), [`8116436`](https://github.com/mastra-ai/mastra/commit/81164363eb225d774e41ff27da6a5ea611406688), [`c35b962`](https://github.com/mastra-ai/mastra/commit/c35b9625c7e854fcfdeee226a3338a750d0ff211), [`c27c4b9`](https://github.com/mastra-ai/mastra/commit/c27c4b9f137df5414fca4e45896aceccff6b0ed5), [`08b3b59`](https://github.com/mastra-ai/mastra/commit/08b3b590dd960dee6c9a6e39272f8927d803db6e), [`b3c3b18`](https://github.com/mastra-ai/mastra/commit/b3c3b189121489a3a51a8fd8204b569be9a89fe5), [`4084113`](https://github.com/mastra-ai/mastra/commit/408411370fc48a822e8b616b3b63f9409774e0e9), [`70cb714`](https://github.com/mastra-ai/mastra/commit/70cb7149c8f16f478e15b58498254a53181750a4), [`91cf0e0`](https://github.com/mastra-ai/mastra/commit/91cf0e027e511b871481a8576b56b7af83b15afd), [`7f9da22`](https://github.com/mastra-ai/mastra/commit/7f9da22efd5aa595e138a31de55a5f0f2f28b33d)]:
+  - @mastra/core@1.37.0
+
 ## 0.2.0-alpha.1
 
 ### Patch Changes

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-acp
 description: Documentation for @mastra/acp. Use when working with @mastra/acp APIs, configuration, or implementation.
 metadata:
   package: "@mastra/acp"
-  version: "0.2.0-alpha.1"
+  version: "0.2.1-alpha.0"
 ---
 
 ## When to use
@@ -16,7 +16,12 @@ Read the individual reference documents for detailed explanations and code examp
 
 ### Docs
 
-- [ACP](references/docs-agents-acp.md) - Wrap ACP-compatible coding agents as Mastra tools or sub-agents.
+- [Agent Client Protocol (ACP)](references/docs-agents-acp.md) - Wrap ACP-compatible coding agents as Mastra tools or sub-agents.
+
+### Reference
+
+- [Reference: AcpAgent class](references/reference-acp-acp-agent.md) - API reference for the AcpAgent class, which wraps an ACP-compatible coding agent as a Mastra subagent.
+- [Reference: createACPTool()](references/reference-acp-create-acp-tool.md) - API reference for createACPTool(), which wraps an ACP-compatible coding agent as a Mastra tool.
 
 
 Read [assets/SOURCE_MAP.json](assets/SOURCE_MAP.json) for source code references.

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.2.0-alpha.1",
+  "version": "0.2.1-alpha.0",
   "package": "@mastra/acp",
   "exports": {},
   "modules": {}

package/dist/docs/references/docs-agents-acp.md

@@ -1,8 +1,8 @@
-# ACP (Agent Client Protocol)
+# Agent Client Protocol
 
 Mastra supports the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/overview/introduction) for running ACP-compatible coding agents from a Mastra agent. Use `@mastra/acp` to wrap a coding agent process as a Mastra tool or as a subagent.
 
-ACP is useful for coding agents such as Claude Code, Amp, Codex, or any other executable that implements the Agent Client Protocol over standard input and output.
+ACP is useful for coding agents such as Claude Code, Amp, Codex, or any other executable that implements ACP over standard input and output.
 
 ## When to use ACP
 
@@ -23,14 +23,14 @@ The flow is:
 3. The client sends ACP `initialize` and `session/new` requests.
 4. Mastra sends the user task to the ACP agent with `session/prompt`.
 5. The ACP agent streams session updates and message chunks back to Mastra.
-6. Mastra returns the buffered output, emits streaming chunks, or suspends for permission input.
-7. The ACP process stays alive by default, or stops after the prompt when `persistSession` is `false`.
+6. Mastra returns the buffered output, emits streaming chunks, or handles permission input.
+7. The ACP connection stops the process after the prompt when `persistSession` is `false`; `AcpAgent` can keep a reusable process alive across calls by default.
 
 During execution, the ACP client also handles permission requests and file operations. File reads and writes go through Mastra's `Workspace`, so the ACP agent operates inside the workspace you provide.
 
 ## Getting started
 
-Install `@mastra/acp` in a project that already uses `@mastra/core`:
+Install `@mastra/acp` in a project that already uses `@mastra/core`. The package requires `@mastra/core` version `1.34.0` or later.
 
 **npm**:
 
@@ -58,14 +58,12 @@ bun add @mastra/acp
 
 `@mastra/acp` exports two APIs:
 
-- `createACPTool`: Create a Mastra tool that sends a `task` string to an ACP agent and returns an `output` string.
-- `AcpAgent`: Wrap an ACP agent as a Mastra subagent with `generate()` and `stream()` support.
-
-The package requires `@mastra/core` version `1.34.0` or later.
+- [`createACPTool()`](https://mastra.ai/reference/acp/create-acp-tool): Create a Mastra tool that sends a `task` string to an ACP agent and returns an `output` string.
+- [`AcpAgent`](https://mastra.ai/reference/acp/acp-agent): Wrap an ACP agent as a Mastra subagent with `generate()` and `stream()` support.
 
 ## Use ACP as a subagent
 
-Use `AcpAgent` when a parent Mastra agent should delegate directly to an ACP-compatible coding agent as a subagent. Create the ACP agent, then register it in the parent agent's `agents` map.
+Use `AcpAgent` when a parent Mastra agent should delegate directly to an ACP-compatible coding agent as a subagent.
 
 ```typescript
 import { AcpAgent } from '@mastra/acp'
@@ -84,18 +82,18 @@ export const codeSupervisor = new Agent({
   id: 'code-supervisor',
   name: 'Code Supervisor',
   instructions: 'Delegate code editing tasks to the code-agent subagent.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   agents: {
     codeAgent,
   },
 })
 ```
 
-`AcpAgent.generate()` buffers the ACP response and returns it as text. `AcpAgent.stream()` emits Mastra `text-delta` chunks as ACP `agent_message_chunk` updates arrive.
+See the [AcpAgent reference](https://mastra.ai/reference/acp/acp-agent) for all options, methods, and configuration.
 
 ## Use ACP as a tool
 
-Use `createACPTool` when the parent Mastra agent should decide when to call the ACP agent as a tool. The following example creates a code editing tool and registers it on a parent agent:
+Use `createACPTool()` when the parent Mastra agent should decide when to call the ACP agent as a tool.
 
 ```typescript
 import { createACPTool } from '@mastra/acp'
@@ -113,178 +111,43 @@ export const codeSupervisor = new Agent({
   id: 'code-supervisor',
   name: 'Code Supervisor',
   instructions: 'Use the code-agent tool when a task requires repository inspection or code edits.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   tools: {
     codeAgentTool,
   },
 })
 ```
 
-Use the `command` and `args` required by the ACP-compatible agent you run. The tool input schema has a single `task` string, and the output schema returns the final ACP response as `output`.
-
-If the ACP agent requests permission, the tool can suspend and resume through Mastra's tool suspension flow. Use `onPermissionRequest` when you need custom permission behavior.
-
-## Options reference
-
-`createACPTool` and `AcpAgent` accept the same ACP connection options. `AcpAgent` also accepts `name` to set the display name used during agent delegation.
-
-| Option                | Type                             | Description                                                                             |
-| --------------------- | -------------------------------- | --------------------------------------------------------------------------------------- |
-| `id`                  | `string`                         | Unique tool or subagent identifier.                                                     |
-| `description`         | `string`                         | Description shown to the model when it can call the tool or delegate to the subagent.   |
-| `command`             | `string`                         | ACP agent executable to spawn.                                                          |
-| `args`                | `string[]`                       | Arguments passed to the ACP agent executable.                                           |
-| `env`                 | `Record<string, string>`         | Environment variables to merge with the current process environment.                    |
-| `cwd`                 | `string`                         | Working directory for the ACP process, ACP session, and default workspace.              |
-| `session`             | `Partial<NewSessionRequest>`     | ACP session creation options. Defaults to `cwd` or `process.cwd()` and no MCP servers.  |
-| `initialize`          | `Partial<InitializeRequest>`     | ACP initialization options. Defaults to Mastra client information and protocol version. |
-| `authMethodId`        | `string`                         | ACP authentication method ID to invoke after initialization.                            |
-| `persistSession`      | `boolean`                        | Keep the ACP process alive after execution. Defaults to `true`.                         |
-| `onPermissionRequest` | `(request) => Promise<Response>` | Callback for ACP permission requests. Defaults to selecting the first option.           |
-| `workspace`           | `Workspace`                      | Workspace used for ACP file reads and writes.                                           |
-| `model`               | `string`                         | Model ID to select after session creation via the ACP `session/set_model` method.       |
+See the [createACPTool() reference](https://mastra.ai/reference/acp/create-acp-tool) for all options and configuration.
 
 ## Model selection
 
-ACP agents may expose selectable models. Instead of setting an environment variable like `ANTHROPIC_MODEL`, you can pass a `model` ID directly in the configuration.
-
-### Discover available models
-
-Call `getAvailableModels()` to see which models the ACP agent supports. This starts the agent process and returns the model list from the session:
-
-```typescript
-import { AcpAgent } from '@mastra/acp'
-
-const codeAgent = new AcpAgent({
-  id: 'code-agent',
-  description: 'An ACP-compatible coding agent',
-  command: 'claude',
-  args: ['--acp'],
-})
-
-const models = await codeAgent.getAvailableModels()
-// [{ modelId: 'claude-sonnet-4-20250514', name: 'Claude Sonnet' }, ...]
-```
-
-### Set the model
+ACP agents may expose selectable models. Pass `model` in the ACP configuration to select a model after session creation, or use `AcpAgent.getAvailableModels()` and `AcpAgent.setModel()` to manage models at runtime.
 
-Pass the `model` option to select a model at connection time:
-
-```typescript
-import { AcpAgent } from '@mastra/acp'
-
-export const codeAgent = new AcpAgent({
-  id: 'code-agent',
-  description: 'An ACP-compatible coding agent',
-  command: 'claude',
-  args: ['--acp'],
-  model: '__AI_SDK_ANTHROPIC_MODEL_SONNET__',
-})
-```
-
-You can also change the model at runtime with `setModel()`:
-
-```typescript
-await codeAgent.setModel('__AI_SDK_ANTHROPIC_MODEL_SONNET__')
-```
-
-If the ACP agent advertises available models and your model ID doesn't match any of them, Mastra throws an error listing the valid options:
-
-```text
-Model "bad-model-id" is not available. Available models: claude-sonnet-4-20250514, claude-haiku-4-20250514
-```
-
-If the agent doesn't advertise a model list, the value is passed through without validation.
+See the [AcpAgent model management methods](https://mastra.ai/reference/acp/acp-agent) for examples.
 
 ## Session lifecycle
 
-`createACPTool` and `AcpAgent` start the configured command on first use and create an ACP session. By default, `persistSession` is `true`, so the child process stays alive across calls.
-
-Use the default persistent session when:
-
-- The ACP agent benefits from keeping conversation or repository context.
-- Startup is expensive and repeated calls should reuse the same process.
-- A parent agent may delegate several related tasks to the same coding agent.
+`AcpAgent` starts the configured command on first use and creates an ACP session. By default, `persistSession` is `true`, so the child process stays alive across calls. Set `persistSession: false` when each prompt should run in an isolated process.
 
-Set `persistSession: false` when each prompt should run in an isolated process:
-
-```typescript
-import { AcpAgent } from '@mastra/acp'
-
-export const codeAgent = new AcpAgent({
-  id: 'code-agent',
-  description: 'Run one isolated ACP coding task',
-  command: 'acp-agent',
-  args: ['--stdio'],
-  cwd: process.cwd(),
-  persistSession: false,
-})
-```
-
-With `persistSession: false`, `@mastra/acp` stops the ACP process after each prompt completes.
+See the [AcpAgent session lifecycle](https://mastra.ai/reference/acp/acp-agent) section for details.
 
 ## Permission handling
 
-ACP agents may ask the client to choose a permission option before they continue. By default, `@mastra/acp` selects the first option returned by the ACP agent.
-
-Pass `onPermissionRequest` to inspect the request and return the selected option yourself:
-
-```typescript
-import { createACPTool } from '@mastra/acp'
-
-export const codeAgentTool = createACPTool({
-  id: 'code-agent',
-  description: 'Use an ACP-compatible coding agent',
-  command: 'acp-agent',
-  args: ['--stdio'],
-  async onPermissionRequest(request) {
-    const allowOption = request.options.find(option => option.name === 'Allow')
-
-    if (!allowOption) {
-      return { outcome: { outcome: 'cancelled' } }
-    }
-
-    return {
-      outcome: {
-        outcome: 'selected',
-        optionId: allowOption.optionId,
-      },
-    }
-  },
-})
-```
+ACP agents may ask the client to choose a permission option before they continue. By default, `@mastra/acp` selects the first option returned by the ACP agent. Pass `onPermissionRequest` when you need custom permission behavior.
 
-Use this callback to enforce local policy, inspect the permission title, or route the decision to your own approval flow.
+See the [createACPTool() permission handling](https://mastra.ai/reference/acp/create-acp-tool) section for a complete example.
 
 ## Workspace integration
 
-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` as the filesystem root.
-
-Pass a custom `Workspace` when the ACP agent should read and write through a specific filesystem implementation:
-
-```typescript
-import { AcpAgent } from '@mastra/acp'
-import { LocalFilesystem, Workspace } from '@mastra/core/workspace'
-
-const workspace = new Workspace({
-  filesystem: new LocalFilesystem({
-    root: process.cwd(),
-  }),
-})
-
-export const codeAgent = new AcpAgent({
-  id: 'code-agent',
-  description: 'Run coding tasks in a controlled workspace',
-  command: 'acp-agent',
-  args: ['--stdio'],
-  workspace,
-})
-```
+ACP file operations go through Mastra's workspace abstraction. `AcpAgent` can use a `workspace` option, and `createACPTool()` uses the current Mastra workspace from the tool execution context when one is available. Without a workspace, `@mastra/acp` falls back to a `Workspace` backed by `LocalFilesystem` at `cwd` or `process.cwd()`.
 
-Use `cwd` and `workspace` together when the ACP process should start in one directory but file operations should use an explicitly configured workspace root.
+See the [AcpAgent workspace integration](https://mastra.ai/reference/acp/acp-agent) section for custom workspace examples.
 
 ## Related
 
+- [AcpAgent reference](https://mastra.ai/reference/acp/acp-agent)
+- [createACPTool() reference](https://mastra.ai/reference/acp/create-acp-tool)
 - [Agent reference](https://mastra.ai/reference/agents/agent)
 - [Subagents](https://mastra.ai/docs/agents/supervisor-agents)
 - [Agent Client Protocol introduction](https://agentclientprotocol.com/overview/introduction)

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

@@ -0,0 +1,228 @@
+# AcpAgent class
+
+The `AcpAgent` class wraps an Agent Client Protocol (ACP)-compatible coding agent as a Mastra subagent. Use it when a parent Mastra agent should delegate repository inspection, code edits, or other ACP-backed tasks to a named subagent.
+
+If you want the parent agent to call the ACP agent as a tool instead, use [`createACPTool()`](https://mastra.ai/reference/acp/create-acp-tool).
+
+## Usage example
+
+Register an ACP-compatible coding agent in a parent agent's `agents` map:
+
+```typescript
+import { AcpAgent } from '@mastra/acp'
+import { Agent } from '@mastra/core/agent'
+
+const codeAgent = new AcpAgent({
+  id: 'code-agent',
+  name: 'Code Agent',
+  description: 'An ACP-compatible coding agent that can inspect and edit files',
+  command: 'acp-agent',
+  args: ['--stdio'],
+  cwd: process.cwd(),
+})
+
+export const codeSupervisor = new Agent({
+  id: 'code-supervisor',
+  name: 'Code Supervisor',
+  instructions: 'Delegate code editing tasks to the code-agent subagent.',
+  model: 'openai/gpt-5.5',
+  agents: {
+    codeAgent,
+  },
+})
+```
+
+For Claude Code, ACP support is provided by the `@agentclientprotocol/claude-agent-acp` bridge package. Configure the ACP agent command to run the bridge, then select a Claude model after session creation:
+
+```typescript
+import { AcpAgent } from '@mastra/acp'
+
+export const claudeCodeAgent = new AcpAgent({
+  id: 'claude-code-agent',
+  name: 'Claude Code Agent',
+  description: 'Use Claude Code through ACP.',
+  command: 'npx',
+  args: ['@agentclientprotocol/claude-agent-acp'],
+  cwd: process.cwd(),
+  model: 'claude-sonnet-4-6',
+})
+```
+
+## Constructor parameters
+
+**id** (`string`): Unique identifier for the subagent.
+
+**name** (`string`): Display name used during agent delegation. Defaults to \`id\`.
+
+**description** (`string`): Description shown to the model when it can delegate to this subagent.
+
+**command** (`string`): ACP agent executable to spawn.
+
+**args** (`string[]`): Arguments passed to the ACP agent executable. (Default: `[]`)
+
+**env** (`Record<string, string>`): Environment variables to merge with the current process environment when spawning the ACP process.
+
+**cwd** (`string`): Working directory for the ACP process and ACP session. Also used as the default local filesystem base path. (Default: `process.cwd()`)
+
+**session** (`Partial<NewSessionRequest>`): ACP session creation options. Defaults to \`cwd\` or \`process.cwd()\` and an empty MCP server list.
+
+**initialize** (`Partial<InitializeRequest>`): ACP initialization options. Defaults to Mastra client information, the current ACP protocol version, and read/write filesystem capabilities.
+
+**authMethodId** (`string`): ACP authentication method ID to invoke after initialization and before session creation.
+
+**persistSession** (`boolean`): Whether to keep the ACP process and session alive after each prompt. Set to \`false\` to stop the process after each prompt completes. (Default: `true`)
+
+**onPermissionRequest** (`(request: RequestPermissionRequest) => Promise<RequestPermissionResponse>`): Callback invoked when the ACP agent requests permission. Defaults to selecting the first permission option, or cancelling when no option is available.
+
+**workspace** (`Workspace`): Workspace used for ACP file read and write requests. Defaults to a \`Workspace\` backed by \`LocalFilesystem\` at \`cwd\` or \`process.cwd()\`.
+
+**model** (`ModelId`): Model ID to select after ACP session creation using the ACP \`session/set\_model\` method.
+
+## Properties
+
+**id** (`TId`): Readonly subagent identifier from the constructor options.
+
+**name** (`string`): Readonly display name for this subagent.
+
+**description** (`string`): Readonly description shown when the parent agent can delegate to this subagent.
+
+**connection** (`ACPConnection`): Readonly ACP connection used to start the agent process, create sessions, send prompts, stream updates, and manage models.
+
+## Methods
+
+### Generation
+
+#### `generate(messages, options?)`
+
+Sends the prompt to the ACP agent, buffers text chunks from the ACP response, and returns a Mastra subagent generate result.
+
+```typescript
+const result = await codeAgent.generate('Inspect the repository and summarize the test setup')
+
+console.log(result.text)
+```
+
+#### `stream(messages, options?)`
+
+Sends the prompt to the ACP agent and returns a Mastra subagent stream result. ACP `agent_message_chunk` updates are emitted as Mastra `text-delta` chunks.
+
+```typescript
+const result = await codeAgent.stream('Refactor the selected module and explain each change')
+
+for await (const chunk of result.fullStream) {
+  if (chunk.type === 'text-delta') {
+    process.stdout.write(chunk.payload.text)
+  }
+}
+```
+
+`resumeGenerate()` and `resumeStream()` are not supported and throw an error when called.
+
+### Model management
+
+#### `getAvailableModels()`
+
+Starts the ACP process if needed and returns the model list advertised by the ACP session.
+
+```typescript
+const models = await codeAgent.getAvailableModels()
+// [{ modelId: 'claude-sonnet-4-6', name: 'Claude Sonnet' }, ...]
+```
+
+#### `setModel(modelId)`
+
+Selects a model for the active ACP session. If the ACP agent advertises available models, the model ID must match one of them.
+
+```typescript
+await codeAgent.setModel('claude-sonnet-4-6')
+```
+
+## Session lifecycle
+
+`AcpAgent` starts the configured `command` on first use, initializes the ACP client, and creates an ACP session. By default, `persistSession` is `true`, so the process and session stay alive across `generate()`, `stream()`, `getAvailableModels()`, and `setModel()` calls.
+
+Set `persistSession: false` when each prompt should run in a fresh ACP process:
+
+```typescript
+import { AcpAgent } from '@mastra/acp'
+
+export const codeAgent = new AcpAgent({
+  id: 'code-agent',
+  description: 'Run one isolated ACP coding task',
+  command: 'acp-agent',
+  args: ['--stdio'],
+  cwd: process.cwd(),
+  persistSession: false,
+})
+```
+
+With `persistSession: false`, `@mastra/acp` stops the ACP process after each prompt completes.
+
+## 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.
+
+Pass a custom `Workspace` when the ACP agent should read and write through a specific filesystem implementation:
+
+```typescript
+import { AcpAgent } from '@mastra/acp'
+import { LocalFilesystem, Workspace } from '@mastra/core/workspace'
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({
+    basePath: process.cwd(),
+  }),
+})
+
+export const codeAgent = new AcpAgent({
+  id: 'code-agent',
+  description: 'Run coding tasks in a controlled workspace',
+  command: 'acp-agent',
+  args: ['--stdio'],
+  workspace,
+})
+```
+
+Use `cwd` and `workspace` together when the ACP process should start in one directory but file operations should use an explicitly configured workspace root.
+
+## Permission handling
+
+ACP agents may ask the client to choose a permission option before they continue. By default, `AcpAgent` selects the first option returned by the ACP agent, or cancels when no option is available.
+
+Pass `onPermissionRequest` to inspect the request and return your own permission response:
+
+```typescript
+import { AcpAgent } from '@mastra/acp'
+
+export const codeAgent = new AcpAgent({
+  id: 'code-agent',
+  description: 'Use an ACP-compatible coding agent',
+  command: 'acp-agent',
+  args: ['--stdio'],
+  async onPermissionRequest(request) {
+    const allowOption = request.options.find(option => option.name === 'Allow')
+
+    if (!allowOption) {
+      return { outcome: { outcome: 'cancelled' } }
+    }
+
+    return {
+      outcome: {
+        outcome: 'selected',
+        optionId: allowOption.optionId,
+      },
+    }
+  },
+})
+```
+
+Use this callback to enforce local policy, inspect the permission title, or route the decision to your own approval flow.
+
+## Related
+
+- [Agent Client Protocol docs](https://mastra.ai/docs/agents/acp)
+- [createACPTool() reference](https://mastra.ai/reference/acp/create-acp-tool)
+- [Agent reference](https://mastra.ai/reference/agents/agent)
+- [Subagents](https://mastra.ai/docs/agents/supervisor-agents)
+- [Agent Client Protocol introduction](https://agentclientprotocol.com/overview/introduction)
+- [Agent Client Protocol schema](https://agentclientprotocol.com/protocol/schema)