ACP and parent agents

The Agent Client Protocol (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.

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.

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.

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 starts a stdio child, creates a session, sends one prompt, and prints the text:

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.

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 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 covers the tools a session can use and the rules that apply to them.
• CLI reference lists the --acp flags.