@mastra/acp 0.1.0 → 0.2.0-alpha.1

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @mastra/acp
 
+## 0.2.0-alpha.1
+
+### 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 [[`c35b962`](https://github.com/mastra-ai/mastra/commit/c35b9625c7e854fcfdeee226a3338a750d0ff211), [`4084113`](https://github.com/mastra-ai/mastra/commit/408411370fc48a822e8b616b3b63f9409774e0e9)]:
+  - @mastra/core@1.37.0-alpha.8
+
+## 0.2.0-alpha.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.
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -148,5 +148,58 @@ By default, the ACP workspace uses `cwd` as its filesystem root. Pass a Mastra `
 | `persistSession`      | `boolean`                        | Keep the ACP process alive after execution. Defaults to `true`.                        |
 | `onPermissionRequest` | `(request) => Promise<Response>` | Callback for ACP permission requests.                                                  |
 | `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.      |
 
 `AcpAgent` also accepts `name` to set the display name used by Mastra agent delegation.
+
+## Configure the model
+
+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
+
+Pass the `model` option to select a model at connection time:
+
+```typescript
+import { AcpAgent } from '@mastra/acp';
+
+const codeAgent = new AcpAgent({
+  id: 'code-agent',
+  description: 'An ACP-compatible coding agent',
+  command: 'claude',
+  args: ['--acp'],
+  model: 'claude-sonnet-4-20250514',
+});
+```
+
+You can also change the model at runtime with `setModel()`:
+
+```typescript
+await codeAgent.setModel('claude-sonnet-4-20250514');
+```
+
+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.

package/dist/agent.d.ts

@@ -1,3 +1,4 @@
+import type { ModelInfo } from '@agentclientprotocol/sdk';
 import type { AgentGenerateOptions, AgentStreamOptions, SubAgent, SubAgentGenerateResult, SubAgentStreamResult } from '@mastra/core/agent';
 import type { MessageListInput } from '@mastra/core/agent/message-list';
 import type { Mastra } from '@mastra/core/mastra';
@@ -20,6 +21,8 @@ export declare class AcpAgent<TId extends string = string, TRequestContext exten
     __setMemory(_memory: DynamicArgument<any, any>): void;
     getMemory(): undefined;
     getInstructions(): string;
+    getAvailableModels(): Promise<ModelInfo[]>;
+    setModel(modelId: string): Promise<void>;
     generate(messages: MessageListInput, options?: AgentGenerateOptions): Promise<SubAgentGenerateResult>;
     resumeGenerate(): Promise<SubAgentGenerateResult>;
     resumeStream(): Promise<SubAgentStreamResult>;

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,oBAAoB,EAEpB,kBAAkB,EAElB,QAAQ,EACR,sBAAsB,EACtB,oBAAoB,EACrB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAElD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AA0BpD,MAAM,MAAM,eAAe,GAAG,oBAAoB,GAAG;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,qBAAa,QAAQ,CACnB,GAAG,SAAS,MAAM,GAAG,MAAM,EAC3B,eAAe,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,GAAG,OAAO,CAC/D,YAAW,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC;IACzC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC;IACjB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAEjB,OAAO,EAAE,eAAe;IAOpC,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAEvC,cAAc,IAAI,MAAM;IAIxB,QAAQ,IAAI,UAAU,CAAC,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC,UAAU,CAAC,CAAC;IAIlE,YAAY,IAAI,OAAO;IAIvB,WAAW,CAAC,OAAO,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,IAAI;IAErD,SAAS,IAAI,SAAS;IAItB,eAAe,IAAI,MAAM;IAInB,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAmBrG,cAAc,IAAI,OAAO,CAAC,sBAAsB,CAAC;IAIjD,YAAY,IAAI,OAAO,CAAC,oBAAoB,CAAC;IAI7C,MAAM,CAAC,QAAQ,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAsErG,OAAO,CAAC,SAAS;IAWjB,OAAO,CAAC,iBAAiB;CAM1B"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAiB,MAAM,0BAA0B,CAAC;AACzE,OAAO,KAAK,EACV,oBAAoB,EAEpB,kBAAkB,EAElB,QAAQ,EACR,sBAAsB,EACtB,oBAAoB,EACrB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAElD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AA0BpD,MAAM,MAAM,eAAe,GAAG,oBAAoB,GAAG;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,qBAAa,QAAQ,CACnB,GAAG,SAAS,MAAM,GAAG,MAAM,EAC3B,eAAe,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,GAAG,OAAO,CAC/D,YAAW,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC;IACzC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC;IACjB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAEjB,OAAO,EAAE,eAAe;IAOpC,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAEvC,cAAc,IAAI,MAAM;IAIxB,QAAQ,IAAI,UAAU,CAAC,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC,UAAU,CAAC,CAAC;IAIlE,YAAY,IAAI,OAAO;IAIvB,WAAW,CAAC,OAAO,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,IAAI;IAErD,SAAS,IAAI,SAAS;IAItB,eAAe,IAAI,MAAM;IAInB,kBAAkB,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAI1C,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAmBrG,cAAc,IAAI,OAAO,CAAC,sBAAsB,CAAC;IAIjD,YAAY,IAAI,OAAO,CAAC,oBAAoB,CAAC;IAI7C,MAAM,CAAC,QAAQ,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAsErG,OAAO,CAAC,SAAS;IAWjB,OAAO,CAAC,iBAAiB;CAM1B"}

package/dist/connection.d.ts

@@ -1,4 +1,4 @@
-import type { SessionUpdate } from '@agentclientprotocol/sdk';
+import type { ModelInfo, SessionUpdate } from '@agentclientprotocol/sdk';
 import type { CreateACPToolOptions } from './types.js';
 export type ACPStreamEvent = {
     type: 'text';
@@ -17,6 +17,8 @@ export declare class ACPConnection {
     private stderr;
     constructor(options: CreateACPToolOptions);
     get sessionId(): string | undefined;
+    getAvailableModels(): Promise<ModelInfo[]>;
+    setModel(modelId: string): Promise<void>;
     prompt(task: string, signal?: AbortSignal): Promise<string>;
     promptStream(task: string, signal?: AbortSignal): AsyncGenerator<ACPStreamEvent>;
     cancel(): Promise<void>;

package/dist/connection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAYV,aAAa,EAGd,MAAM,0BAA0B,CAAC;AAGlC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAEpD,MAAM,MAAM,cAAc,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,CAAC;AAuEhH,qBAAa,aAAa;IACxB,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;IAEvC,OAAO,CAAC,YAAY,CAAC,CAAiC;IACtD,OAAO,CAAC,UAAU,CAAC,CAAuB;IAC1C,OAAO,CAAC,OAAO,CAAC,CAAqB;IACrC,OAAO,CAAC,iBAAiB,CAAC,CAAgB;IAC1C,OAAO,CAAC,aAAa,CAAC,CAAc;IACpC,OAAO,CAAC,MAAM,CAAM;gBAER,OAAO,EAAE,oBAAoB;IAIzC,IAAI,SAAS,IAAI,MAAM,GAAG,SAAS,CAElC;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAY1D,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,cAAc,CAAC,cAAc,CAAC;IAgEjF,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAU7B,UAAU,IAAI,IAAI;YAaJ,eAAe;YASf,UAAU;IA0CxB,OAAO,CAAC,oBAAoB;IAc5B,OAAO,CAAC,oBAAoB;IAQ5B,OAAO,CAAC,2BAA2B;IAQnC,OAAO,CAAC,UAAU;CAanB"}
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAGV,SAAS,EAUT,aAAa,EAGd,MAAM,0BAA0B,CAAC;AAGlC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAEpD,MAAM,MAAM,cAAc,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,CAAC;AAuEhH,qBAAa,aAAa;IACxB,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;IAEvC,OAAO,CAAC,YAAY,CAAC,CAAiC;IACtD,OAAO,CAAC,UAAU,CAAC,CAAuB;IAC1C,OAAO,CAAC,OAAO,CAAC,CAAqB;IACrC,OAAO,CAAC,iBAAiB,CAAC,CAAgB;IAC1C,OAAO,CAAC,aAAa,CAAC,CAAc;IACpC,OAAO,CAAC,MAAM,CAAM;gBAER,OAAO,EAAE,oBAAoB;IAIzC,IAAI,SAAS,IAAI,MAAM,GAAG,SAAS,CAElC;IAEK,kBAAkB,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAK1C,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBxC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAY1D,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,cAAc,CAAC,cAAc,CAAC;IAgEjF,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAU7B,UAAU,IAAI,IAAI;YAaJ,eAAe;YASf,UAAU;IAwDxB,OAAO,CAAC,oBAAoB;IAc5B,OAAO,CAAC,oBAAoB;IAQ5B,OAAO,CAAC,2BAA2B;IAQnC,OAAO,CAAC,UAAU;CAanB"}

package/dist/docs/SKILL.md

@@ -0,0 +1,22 @@
+---
+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"
+---
+
+## When to use
+
+Use this skill whenever you are working with @mastra/acp to obtain the domain-specific knowledge.
+
+## How to use
+
+Read the individual reference documents for detailed explanations and code examples.
+
+### Docs
+
+- [ACP](references/docs-agents-acp.md) - Wrap ACP-compatible coding agents as Mastra tools or sub-agents.
+
+
+Read [assets/SOURCE_MAP.json](assets/SOURCE_MAP.json) for source code references.

package/dist/docs/assets/SOURCE_MAP.json

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

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

@@ -0,0 +1,291 @@
+# ACP (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.
+
+## When to use ACP
+
+- A Mastra agent should delegate code inspection, editing, or repository tasks to an external coding agent.
+- An ACP-compatible agent process should stay alive across calls so it can keep session context.
+- A parent agent needs real-time output from a coding agent while the task runs.
+- An ACP-compatible agent needs permission prompts before it reads files, writes files, or runs actions.
+- File access should go through Mastra's workspace abstraction instead of direct process-only file access.
+
+## How ACP works
+
+`@mastra/acp` starts the configured ACP agent command as a child process and communicates with it using newline-delimited JSON over standard input and output.
+
+The flow is:
+
+1. Configure `command`, `args`, and optional connection settings.
+2. `@mastra/acp` spawns the ACP agent process on first use.
+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`.
+
+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`:
+
+**npm**:
+
+```bash
+npm install @mastra/acp
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/acp
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/acp
+```
+
+**Bun**:
+
+```bash
+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.
+
+## 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.
+
+```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.4',
+  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.
+
+## 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:
+
+```typescript
+import { createACPTool } from '@mastra/acp'
+import { Agent } from '@mastra/core/agent'
+
+const codeAgentTool = createACPTool({
+  id: 'code-agent',
+  description: 'Use an ACP-compatible coding agent to inspect and edit code',
+  command: 'acp-agent',
+  args: ['--stdio'],
+  cwd: process.cwd(),
+})
+
+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',
+  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.       |
+
+## 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
+
+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.
+
+## 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.
+
+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.
+
+## 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,
+      },
+    }
+  },
+})
+```
+
+Use this callback to enforce local policy, inspect the permission title, or route the decision to your own approval flow.
+
+## 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,
+})
+```
+
+Use `cwd` and `workspace` together when the ACP process should start in one directory but file operations should use an explicitly configured workspace root.
+
+## Related
+
+- [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)

package/dist/index.cjs

@@ -9,7 +9,6 @@ var stream = require('stream');
 var sdk = require('@agentclientprotocol/sdk');
 var workspace = require('@mastra/core/workspace');
 var tools = require('@mastra/core/tools');
-var zod = require('zod');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -82,6 +81,22 @@ var ACPConnection = class {
   get sessionId() {
     return this.session?.sessionId;
   }
+  async getAvailableModels() {
+    await this.ensureConnected();
+    return this.session?.models?.availableModels ?? [];
+  }
+  async setModel(modelId) {
+    await this.ensureConnected();
+    const available = this.session?.models?.availableModels;
+    if (available && !available.some((m) => m.modelId === modelId)) {
+      const ids = available.map((m) => m.modelId).join(", ") || "(none)";
+      throw new Error(`Model "${modelId}" is not available. Available models: ${ids}`);
+    }
+    await this.connection.unstable_setSessionModel({
+      sessionId: this.session.sessionId,
+      modelId
+    });
+  }
   async prompt(task, signal) {
     const parts = [];
     for await (const event of this.promptStream(task, signal)) {
@@ -193,6 +208,17 @@ var ACPConnection = class {
         await this.connection.authenticate({ methodId: this.options.authMethodId });
       }
       this.session = await this.connection.newSession(this.getNewSessionRequest());
+      if (this.options.model) {
+        const available = this.session.models?.availableModels;
+        if (available && !available.some((m) => m.modelId === this.options.model)) {
+          const ids = available.map((m) => m.modelId).join(", ") || "(none)";
+          throw new Error(`Model "${this.options.model}" is not available. Available models: ${ids}`);
+        }
+        await this.connection.unstable_setSessionModel({
+          sessionId: this.session.sessionId,
+          modelId: this.options.model
+        });
+      }
     } catch (error) {
       this.disconnect();
       throw this.withStderr(error);
@@ -342,6 +368,12 @@ var AcpAgent = class {
   getInstructions() {
     return "";
   }
+  async getAvailableModels() {
+    return this.connection.getAvailableModels();
+  }
+  async setModel(modelId) {
+    return this.connection.setModel(modelId);
+  }
   async generate(messages, options) {
     const prompt = this.getPrompt(messages, options?.instructions);
     const text = await this.connection.prompt(
@@ -576,32 +608,103 @@ function createACPTool(options) {
   return tools.createTool({
     id: options.id,
     description: options.description,
-    inputSchema: zod.z.object({
-      task: zod.z.string().describe("The task to send to the ACP agent")
-    }),
-    outputSchema: zod.z.object({
-      output: zod.z.string().describe("The output of the ACP agent")
-    }),
-    suspendSchema: zod.z.object({
-      permissionRequest: zod.z.object({
-        title: zod.z.string().describe("The title of the permission request"),
-        options: zod.z.array(
-          zod.z.object({
-            optionId: zod.z.string().describe("The option id to select"),
-            name: zod.z.string().describe("The title of the permission request")
-          })
-        )
-      })
-    }),
-    resumeSchema: zod.z.union([
-      zod.z.object({
-        optionId: zod.z.string().optional().describe("The option id to select"),
-        outcome: zod.z.literal("selected").optional().describe("The outcome of the permission request")
-      }),
-      zod.z.object({
-        outcome: zod.z.literal("cancelled").optional().describe("The outcome of the permission request")
-      })
-    ]),
+    inputSchema: {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "type": "object",
+      "properties": {
+        "task": {
+          "type": "string",
+          "description": "The task to send to the ACP agent"
+        }
+      },
+      "required": [
+        "task"
+      ]
+    },
+    outputSchema: {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "type": "object",
+      "properties": {
+        "output": {
+          "type": "string",
+          "description": "The output of the ACP agent"
+        }
+      },
+      "required": [
+        "output"
+      ]
+    },
+    suspendSchema: {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "type": "object",
+      "properties": {
+        "permissionRequest": {
+          "type": "object",
+          "properties": {
+            "title": {
+              "type": "string",
+              "description": "The title of the permission request"
+            },
+            "options": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "optionId": {
+                    "type": "string",
+                    "description": "The option id to select"
+                  },
+                  "name": {
+                    "type": "string",
+                    "description": "The title of the permission request"
+                  }
+                },
+                "required": [
+                  "optionId",
+                  "name"
+                ]
+              }
+            }
+          },
+          "required": [
+            "title",
+            "options"
+          ]
+        }
+      },
+      "required": [
+        "permissionRequest"
+      ]
+    },
+    resumeSchema: {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "anyOf": [
+        {
+          "type": "object",
+          "properties": {
+            "optionId": {
+              "description": "The option id to select",
+              "type": "string"
+            },
+            "outcome": {
+              "description": "The outcome of the permission request",
+              "type": "string",
+              "const": "selected"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "properties": {
+            "outcome": {
+              "description": "The outcome of the permission request",
+              "type": "string",
+              "const": "cancelled"
+            }
+          }
+        }
+      ]
+    },
     execute: async ({ task }, context) => {
       const workspace = await context?.mastra?.getWorkspace();
       const connection = new ACPConnection({