ACP Tools

GoClaw exposes ACP control to the agent through two tools:

• acp_control
• acp_inspect

These are different from the user-facing /acp slash command. Use /acp when you want to control ACP manually from chat. Use these tools when the agent itself needs to attach to, inspect, or steer an ACP session.

acp_control

acp_control changes ACP session state for the current GoClaw session identity.

Supported actions:

• attach
• detach
• close
• cancel
• set_mode
• list_models
• set_model
• steer
• btw

attach currently supports two drivers over local stdio: cursor and grok. After attach, GoClaw applies the configured acp.drivers.<driver>.model alias (default claude-4.6-opus-high-thinking for Cursor, grok-build for Grok).

attach

Create a new ACP session, or attach to an existing one if sessionId is provided.

{
  "action": "attach",
  "driver": "cursor",
  "cwd": "/path/to/project",
  "mode": "agent"
}

Attach to an existing ACP session:

{
  "action": "attach",
  "driver": "cursor",
  "sessionId": "SESSION_ID"
}

set_mode

Change the attached ACP session mode. Only available when the driver exposes modes — Cursor does, Grok does not, and set_mode against a Grok session returns a clear “ACP driver does not support session modes” error.

{
  "action": "set_mode",
  "mode": "plan"
}

list_models

List the live ACP model aliases accepted by the currently attached Cursor session:

{
  "action": "list_models"
}

This returns the friendly aliases GoClaw accepts for set_model, with the current one marked in the text output.

set_model

Switch the attached Cursor ACP session to a friendly model alias:

{
  "action": "set_model",
  "model": "claude-4.6-opus-high-thinking"
}

steer

Send a text prompt into the attached ACP session:

{
  "action": "steer",
  "message": "Review the patch and summarize the remaining risks."
}

By default, steering detaches after completion. To keep the ACP session attached, set stayAttached to true:

{
  "action": "steer",
  "message": "Stay in ACP mode for one more turn.",
  "stayAttached": true
}

ACP allows only one prompt per session at a time. If a steer hits a busy session and interrupt is false, the tool returns a clear non-fatal message so the agent can wait or retry with interrupt: true to take over.

When background is true, the steer returns right away with a “running” status; the session stays attached, the sub-agent’s activity streams live, and the agent is woken with an [acp-subagent-complete] summary when the turn finishes. Use acp_inspect to check progress in the meantime.

btw

Ask the attached ACP agent a quick side question without abandoning its current task. It interrupts the in-flight turn, answers with full context, then the agent resumes:

{
  "action": "btw",
  "message": "Which files have you changed so far?"
}

cancel

Cancel the currently running ACP prompt without closing the session:

{
  "action": "cancel"
}

detach

Detach GoClaw from the ACP session while leaving the external ACP session available to re-attach later:

{
  "action": "detach"
}

close

Close the ACP session entirely:

{
  "action": "close"
}

acp_inspect

acp_inspect is a read-only view into the ACP state for the current GoClaw session.

Minimal call:

{}

Optional detail hint:

{
  "detail": "full"
}

The tool output can include:

• whether the session is attached
• ACP session ID, driver, transport, mode, and CWD
• current friendly ACP model alias
• current state and buffered event count
• whether a prompt is currently running (the agent is actively working on its turn) or idle
• how long since the session’s last activity
• last assistant text, last question, and last plan overview
• current ACP todo list
• pending interactive requests
• recent driver extension events

This is useful when the agent needs to decide whether to attach, whether an interactive prompt is still pending, or what the attached Cursor session last asked for. It is also how the agent checks on a background steer: the prompt-running flag and last-activity time show whether the delegated agent is still working and how far along it is.

When To Use These Tools

Use ACP tools when the agent must:

• inspect whether an ACP session is already attached
• attach to Cursor before steering an external session
• switch ACP mode before sending a prompt
• inspect the live ACP model aliases before switching models
• switch the attached Cursor session to a specific friendly model alias
• cancel a blocked interactive ACP request
• keep or release ACP attachment intentionally after steering
• delegate a long task with a background steer and stay responsive, checking progress with acp_inspect
• take over a busy session with interrupt, or ask a side question with btw

Do not use ACP tools as a replacement for normal GoClaw conversation unless the task specifically needs an attached ACP session.

See Also

• ACP Sessions — User-facing ACP workflow
• Channel Commands — Manual /acp commands
• Channels — Channel-specific ACP presentation