# ACP and parent agents

> Run Raw as an Agent Client Protocol server over stdio or a local WebSocket, and drive it from a parent agent with createAcpClient, including reverse tools.

The [Agent Client Protocol](https://agentclientprotocol.com/) (ACP) lets a client, such as an editor or another agent, start and drive Raw sessions. Raw implements ACP version 1.

Raw has two ways to serve ACP.

**stdio**

Raw reads JSON-RPC messages from stdin and writes them to stdout, one per line. Diagnostics go to stderr.

```sh
raw --acp --stdio
```

Stdio is the default when you pass only `--acp`.

**WebSocket**

Raw listens on a local WebSocket. Each text frame holds one JSON-RPC message, and a frame can be up to 16 MiB.

```sh
raw --acp --ws --host 127.0.0.1 --port 8765
```

The server binds only to loopback. It rejects binary frames and any request with a browser `Origin` header. It is meant for local clients and parent processes, not for public hosting.

## Sessions

A client calls these standard methods, in this order:

1. `initialize` to negotiate capabilities.
2. `session/new` with an absolute `cwd` to create a session. The `cwd` must already exist.
3. `session/prompt` to send a turn. Raw streams progress as `session/update` notifications, and it answers the prompt only when the turn ends.

Other methods:

| Method           | Purpose                                                                              |
| ---------------- | ------------------------------------------------------------------------------------ |
| `session/list`   | Lists up to 20 recent sessions. Pass `cwd` to filter, and use `nextCursor` for more. |
| `session/load`   | Loads a saved session by ID and replays its visible history as notifications.        |
| `session/resume` | Attaches to a saved session without replaying history.                               |
| `session/cancel` | Stops the current operation. The session stays open for another prompt.              |
| `session/delete` | Permanently removes an inactive session.                                             |

Sessions are saved in the same store as the CLI and the dashboard. A session expires after seven days without committed activity, by default. See [Configuration](https://raw.tlelabs.com/docs/reference/configuration/).

A tool call is one ACP tool call. A batch from `read_file`, `write_file`, or `bash` shows as one tool call, with the input array and one result per entry.

Tools run automatically in ACP sessions. An agent rule with `ask` is the exception. Raw sends that request to the client with `session/request_permission`, and `-y` does not override it.

Each connection owns its sessions. If the connection closes, Raw stops active work and releases the session. The saved session remains, and a later `session/resume` can continue it.

## Parent agents

A parent process can start Raw as a child and drive it with the exported `createAcpClient` helper. The helper runs standard ACP, and it can also register tools that run in the parent process.

The [parent example](https://github.com/lploc94/raw-cli/tree/main/examples/parent-agent.ts) starts a stdio child, creates a session, sends one prompt, and prints the text:

```ts
import { resolve } from "node:path";
import { createAcpClient } from "@tlelabs/raw";


const parent = await createAcpClient({
  command: "raw",
  args: ["--acp", "--stdio", "-y"],
  onUpdate(notification) {
    const update = notification.update;
    if (update.sessionUpdate === "agent_message_chunk" && update.content.type === "text") {
      process.stdout.write(update.content.text);
    }
  },
});


try {
  const sessionId = await parent.newSession(resolve("."));
  const result = await parent.prompt(sessionId, "Summarize this repository");
  process.stdout.write(`\n[${result.stopReason}]\n`);
} finally {
  await parent.close();
}
```

`createAcpClient` takes one of two connection options:

- `command`, `args`, and optional `cwd` and `env` to start a local `raw` process over stdio.
- `url` to connect to a running WebSocket endpoint.

It also takes these optional callbacks:

| Option                           | Called when                                                                                          |
| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `onUpdate(notification)`         | Raw sends a `session/update` notification.                                                           |
| `onPermission(request)`          | An `ask` rule needs an answer. Return the client’s permission response.                              |
| `onInteraction(request, signal)` | Raw asks the user a structured question. Supplying this callback turns on the interaction extension. |

The client object has these methods: `newSession`, `listSessions`, `loadSession`, `resumeSession`, `deleteSession`, `prompt`, `cancel`, `registerTool`, and `close`.

### Reverse tools

A parent can register a tool that Raw can call. The handler runs in the parent process, and its return value goes back to the model as the tool result.

```ts
await parent.registerTool(
  sessionId,
  "lookup_ticket",
  "Look up a ticket in the parent's tracker by ID.",
  {
    type: "object",
    properties: { id: { type: "string" } },
    required: ["id"],
    additionalProperties: false
  },
  async (call, signal) => {
    const ticket = await fetchTicket(String(call.arguments.id), { signal });
    return { content: [{ type: "text", text: JSON.stringify(ticket) }] };
  }
);
```

`fetchTicket` stands in for your own code. The handler receives the call and an abort signal. If the parent disconnects or cancels, the pending call is aborted. Registered tools follow the same agent rules as any other tool, so an `ask` or `deny` rule applies to them.

## Raw extensions

Clients that negotiate Raw’s extensions can use methods that start with `_raw/`. Standard ACP works without them.

| Method                   | Purpose                                                                                                            |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `_raw/runtime/info`      | Returns the selected agent, model alias, limits, exposed tools, and discovered MCP tools. Credentials are omitted. |
| `_raw/session/configure` | Selects tools for later turns in a session.                                                                        |
| `_raw/tool/register`     | Registers a tool whose handler lives in the client. Registration takes a JSON schema, never code.                  |
| `_raw/tool/call`         | Raw asks the client to run a registered tool. Sent from the agent to the client.                                   |
| `_raw/session/compact`   | Compacts the session’s context, the same as `/compact` in the terminal.                                            |

Extension errors use codes in the `-32001` to `-32008` range. The [configuration reference](https://raw.tlelabs.com/docs/reference/configuration/) covers the agent fields that affect ACP sessions.

> **Note:**
>
> ACP does not add methods or slash commands to the model’s tools. The model sees only the tools the agent selects.

## Related

- [Tools](https://raw.tlelabs.com/docs/extend/tools/) covers the tools a session can use and the rules that apply to them.
- [CLI reference](https://raw.tlelabs.com/docs/reference/cli/) lists the `--acp` flags.