@mastra/core/dist/docs/references/reference-acp-create-acp-tool.md

> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# createACPTool()

The `createACPTool()` function creates a Mastra tool that sends a `task` string to an Agent Client Protocol (ACP)-compatible coding agent and returns the final ACP response as `output`. Use it when a parent agent should decide when to call the ACP agent as a tool.

If you want to register the ACP agent as a Mastra subagent instead, use the [`AcpAgent` class](https://mastra.ai/reference/acp/acp-agent).

## Usage example

Create a code editing tool and register 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.5',
  tools: {
    codeAgentTool,
  },
})
```

## Parameters

**id** (`string`): Unique identifier for the Mastra tool.

**description** (`string`): Description shown to the model when it can call this tool.

**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 the ACP connection created for a tool execution disconnects after the 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 option from the shared ACP connection options. During tool execution, createACPTool() passes the current Mastra workspace from the execution context when one is available; otherwise the ACP connection falls back to a local filesystem workspace. Use AcpAgent when you need to provide an explicit workspace instance.

**model** (`ModelId`): Model ID to select after ACP session creation using the ACP session/set\_model method.

## Input schema

**task** (`string`): The task to send to the ACP agent.

## Output schema

**output** (`string`): The final text output returned by the ACP agent.

## Suspend and resume schema

`createACPTool()` defines suspend and resume schemas for permission request payloads. Permission decisions are returned through `onPermissionRequest`; by default, `@mastra/acp` selects the first option returned by the ACP agent, or cancels when no option is available.

### Suspend payload

**permissionRequest** (`{ title: string; options: { optionId: string; name: string }[] }`): Permission request title and selectable options returned by the ACP agent.

### Resume payload

**optionId** (`string`): Permission option ID to select when resuming with outcome: "selected".

**outcome** (`"selected" | "cancelled"`): Permission decision used to continue or cancel the ACP request.

## Session lifecycle

Each tool execution creates an ACP connection, starts the configured `command`, initializes the ACP client, creates an ACP session, and sends the `task` with ACP `session/prompt`.

By default, `persistSession` is `true` for the ACP connection created during tool execution. Set `persistSession: false` when the ACP process should stop as soon as that prompt completes.

Use [`AcpAgent`](https://mastra.ai/reference/acp/acp-agent) when you need a reusable ACP subagent instance with explicit session lifecycle control across calls.

## 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, or cancels when no option is available.

Pass `onPermissionRequest` to inspect the request and return your own permission response:

```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.

## Related

- [Agent Client Protocol docs](https://mastra.ai/docs/agents/acp)
- [AcpAgent class reference](https://mastra.ai/reference/acp/acp-agent)
- [Tool reference](https://mastra.ai/reference/tools/create-tool)
- [Agent Client Protocol introduction](https://agentclientprotocol.com/overview/introduction)
- [Agent Client Protocol schema](https://agentclientprotocol.com/protocol/schema)