> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# ACP Agents

# ACP agents

[Agent Client Protocol (ACP)](https://agentclientprotocol.com/) sessions let WednesdayAI run external coding harnesses (for example Pi, Claude Code, Codex, OpenCode, and Gemini CLI) through an ACP backend plugin.

If you ask WednesdayAI in plain language to "run this in Codex" or "start Claude Code in a thread", WednesdayAI should route that request to the ACP runtime (not the native sub-agent runtime).

## Fast operator flow

Use this when you want a practical `/acp` runbook:

1. Spawn a session:
   * `/acp spawn codex --mode persistent --thread auto`
2. Work in the bound thread (or target that session key explicitly).
3. Check runtime state:
   * `/acp status`
4. Tune runtime options as needed:
   * `/acp model <provider/model>`
   * `/acp permissions <profile>`
   * `/acp timeout <seconds>`
5. Nudge an active session without replacing context:
   * `/acp steer tighten logging and continue`
6. Stop work:
   * `/acp cancel` (stop current turn), or
   * `/acp close` (close session + remove bindings)

## Quick start for humans

Examples of natural requests:

* "Start a persistent Codex session in a thread here and keep it focused."
* "Run this as a one-shot Claude Code ACP session and summarize the result."
* "Use Gemini CLI for this task in a thread, then keep follow-ups in that same thread."

What WednesdayAI should do:

1. Pick `runtime: "acp"`.
2. Resolve the requested harness target (`agentId`, for example `codex`).
3. If thread binding is requested and the current channel supports it, bind the ACP session to the thread.
4. Route follow-up thread messages to that same ACP session until unfocused/closed/expired.

## ACP versus sub-agents

Use ACP when you want an external harness runtime. Use sub-agents when you want WednesdayAI-native delegated runs.

| Area | ACP session | Sub-agent run |
| - | - | - |
| Runtime | ACP backend plugin (for example acpx) | WednesdayAI native sub-agent runtime |
| Session key | `agent:<agentId>:acp:<uuid>` | `agent:<agentId>:subagent:<uuid>` |
| Main commands | `/acp ...` | `/subagents ...` |
| Spawn tool | `sessions_spawn` with `runtime:"acp"` | `sessions_spawn` (default runtime) |

See also [Sub-agents](https://docs.wednesdayai.dev/next/users/tools/subagents.md).

## Thread-bound sessions (channel-agnostic)

When thread bindings are enabled for a channel adapter, ACP sessions can be bound to threads:

* WednesdayAI binds a thread to a target ACP session.
* Follow-up messages in that thread route to the bound ACP session.
* ACP output is delivered back to the same thread.
* Unfocus/close/archive/idle-timeout or max-age expiry removes the binding.

Thread binding support is adapter-specific. If the active channel adapter does not support thread bindings, WednesdayAI returns a clear unsupported/unavailable message.

Required feature flags for thread-bound ACP:

* `acp.enabled=true`
* `acp.dispatch.enabled` is on by default (set `false` to pause ACP dispatch)
* Channel-adapter ACP thread-spawn flag enabled (adapter-specific)
  * Discord: `channels.discord.threadBindings.spawnAcpSessions=true`

### Thread supporting channels

* Any channel adapter that exposes session/thread binding capability.
* Current built-in support: Discord.
* Plugin channels can add support through the same binding interface.

## Start ACP sessions (interfaces)

### From `sessions_spawn`

Use `runtime: "acp"` to start an ACP session from an agent turn or tool call.

```json theme={"dark"}
{
  "task": "Open the repo and summarize failing tests",
  "runtime": "acp",
  "agentId": "codex",
  "thread": true,
  "mode": "session"
}
```

Notes:

* `runtime` defaults to `subagent`, so set `runtime: "acp"` explicitly for ACP sessions.
* If `agentId` is omitted, WednesdayAI uses `acp.defaultAgent` when configured.
* `mode: "session"` requires `thread: true` to keep a persistent bound conversation.
* `mode: "run"` children do not post their output to the channel. When the run ends, the
  requesting agent receives a `task_completion` event with the result and writes the reply
  (default `completionDelivery: "parent"`; see [Sub-agents](https://docs.wednesdayai.dev/next/users/tools/subagents.md#completion-delivery)).
  Run-mode children show up in `subagents list`, and `subagents kill` or `/stop` also cancels
  the ACP turn.

Interface details:

* `task` (required): initial prompt sent to the ACP session.
* `runtime` (required for ACP): must be `"acp"`.
* `agentId` (optional): ACP target harness id. Falls back to `acp.defaultAgent` if set.
* `thread` (optional, default `false`): request thread binding flow where supported.
* `mode` (optional): `run` (one-shot) or `session` (persistent).
  * default is `run`
  * if `thread: true` and mode omitted, WednesdayAI may default to persistent behavior per runtime path
  * `mode: "session"` requires `thread: true`
* `cwd` (optional): requested runtime working directory (validated by backend/runtime policy).
* `label` (optional): operator-facing label used in session/banner text.
* `completionDelivery` (optional, `mode: "run"` only): `"parent"` (default) hands the result to the requesting agent; `"direct"` sends it straight to the requester chat. See [Completion delivery](https://docs.wednesdayai.dev/next/users/tools/subagents.md#completion-delivery).

## Sandbox compatibility

ACP sessions currently run on the host runtime, not inside the WednesdayAI sandbox.

Current limitations:

* If the requester session is sandboxed, ACP spawns are blocked.
  * Error: `Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host. Use runtime="subagent" from sandboxed sessions.`
* `sessions_spawn` with `runtime: "acp"` does not support `sandbox: "require"`.
  * Error: `sessions_spawn sandbox="require" is unsupported for runtime="acp" because ACP sessions run outside the sandbox. Use runtime="subagent" or sandbox="inherit".`

Use `runtime: "subagent"` when you need sandbox-enforced execution.

### From `/acp` command

Use `/acp spawn` for explicit operator control from chat when needed.

```text theme={"dark"}
/acp spawn codex --mode persistent --thread auto
/acp spawn codex --mode oneshot --thread off
/acp spawn codex --thread here
```

Key flags:

* `--mode persistent|oneshot`
* `--thread auto|here|off`
* `--cwd <absolute-path>`
* `--label <name>`

See [Slash Commands](https://docs.wednesdayai.dev/next/users/tools/slash-commands.md).

## Session target resolution

Most `/acp` actions accept an optional session target (`session-key`, `session-id`, or `session-label`).

Resolution order:

1. Explicit target argument (or `--session` for `/acp steer`)
   * tries key
   * then UUID-shaped session id
   * then label
2. Current thread binding (if this conversation/thread is bound to an ACP session)
3. Current requester session fallback

If no target resolves, WednesdayAI returns a clear error (`Unable to resolve session target: ...`).

## Spawn thread modes

`/acp spawn` supports `--thread auto|here|off`.

| Mode | Behavior |
| - | - |
| `auto` | In an active thread: bind that thread. Outside a thread: create/bind a child thread when supported. |
| `here` | Require current active thread; fail if not in one. |
| `off` | No binding. Session starts unbound. |

Notes:

* On non-thread binding surfaces, default behavior is effectively `off`.
* Thread-bound spawn requires channel policy support (for Discord: `channels.discord.threadBindings.spawnAcpSessions=true`).

## ACP controls

Available command family:

* `/acp spawn`
* `/acp cancel`
* `/acp steer`
* `/acp close`
* `/acp status`
* `/acp set-mode`
* `/acp set`
* `/acp cwd`
* `/acp permissions`
* `/acp timeout`
* `/acp model`
* `/acp reset-options`
* `/acp sessions`
* `/acp doctor`
* `/acp install`

`/acp status` shows the effective runtime options and, when available, both runtime-level and backend-level session identifiers.

Some controls depend on backend capabilities. If a backend does not support a control, WednesdayAI returns a clear unsupported-control error.

## ACP command cookbook

| Command | What it does | Example |
| - | - | - |
| `/acp spawn` | Create ACP session; optional thread bind. | `/acp spawn codex --mode persistent --thread auto --cwd /repo` |
| `/acp cancel` | Cancel in-flight turn for target session. | `/acp cancel agent:codex:acp:<uuid>` |
| `/acp steer` | Send steer instruction to running session. | `/acp steer --session support inbox prioritize failing tests` |
| `/acp close` | Close session and unbind thread targets. | `/acp close` |
| `/acp status` | Show backend, mode, state, runtime options, capabilities. | `/acp status` |
| `/acp set-mode` | Set runtime mode for target session. | `/acp set-mode plan` |
| `/acp set` | Generic runtime config option write. | `/acp set model openai/gpt-5.2` |
| `/acp cwd` | Set runtime working directory override. | `/acp cwd /Users/user/Projects/repo` |
| `/acp permissions` | Set approval policy profile. | `/acp permissions strict` |
| `/acp timeout` | Set runtime timeout (seconds). | `/acp timeout 120` |
| `/acp model` | Set runtime model override. | `/acp model anthropic/claude-opus-4-5` |
| `/acp reset-options` | Remove session runtime option overrides. | `/acp reset-options` |
| `/acp sessions` | List recent ACP sessions from store. | `/acp sessions` |
| `/acp doctor` | Backend health, capabilities, actionable fixes. | `/acp doctor` |
| `/acp install` | Print deterministic install and enable steps. | `/acp install` |

## Runtime options mapping

`/acp` has convenience commands and a generic setter.

Equivalent operations:

* `/acp model <id>` maps to runtime config key `model`.
* `/acp permissions <profile>` maps to runtime config key `approval_policy`.
* `/acp timeout <seconds>` maps to runtime config key `timeout`.
* `/acp cwd <path>` updates runtime cwd override directly.
* `/acp set <key> <value>` is the generic path.
  * Special case: `key=cwd` uses the cwd override path.
* `/acp reset-options` clears all runtime overrides for target session.

## acpx harness support (current)

Current acpx built-in harness aliases:

* `pi`
* `claude`
* `codex`
* `opencode`
* `gemini`
* `kimi`

When WednesdayAI uses the acpx backend, prefer these values for `agentId` unless your acpx config defines custom agent aliases.

Direct acpx CLI usage can also target arbitrary adapters via `--agent <command>`, but that raw escape hatch is an acpx CLI feature (not the normal WednesdayAI `agentId` path).

## Required config

Core ACP baseline:

```json5 theme={"dark"}
{
  acp: {
    enabled: true,
    // Optional. Default is true; set false to pause ACP dispatch while keeping /acp controls.
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "codex",
    allowedAgents: ["pi", "claude", "codex", "opencode", "gemini", "kimi"],
    maxConcurrentSessions: 8,
    stream: {
      coalesceIdleMs: 300,
      maxChunkChars: 1200,
    },
    runtime: {
      ttlMinutes: 120,
    },
  },
}
```

Thread binding config is channel-adapter specific. Example for Discord:

```json5 theme={"dark"}
{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        spawnAcpSessions: true,
      },
    },
  },
}
```

If thread-bound ACP spawn does not work, verify the adapter feature flag first:

* Discord: `channels.discord.threadBindings.spawnAcpSessions=true`

See [Configuration Reference](https://docs.wednesdayai.dev/next/admin/gateway/configuration-reference.md).

## Plugin setup for acpx backend

Install and enable plugin:

```bash theme={"dark"}
wednesdayai plugins install acpx
wednesdayai config set plugins.entries.acpx.enabled true
```

Local workspace install during development:

```bash theme={"dark"}
wednesdayai plugins install ./extensions/acpx
```

Then verify backend health:

```text theme={"dark"}
/acp doctor
```

### acpx command and version configuration

By default, the acpx plugin (published as `@openclaw/acpx`) uses the plugin-local pinned binary:

1. Command defaults to `extensions/acpx/node_modules/.bin/acpx`.
2. Expected version defaults to the exact `acpx` version in the plugin's `package.json` (`dependencies.acpx`).
3. Startup registers ACP backend immediately as not-ready.
4. A background ensure job verifies `acpx --version`.
5. If the plugin-local binary is missing or mismatched, it runs:
   `npm install --omit=dev --no-save acpx@<pinned>` and re-verifies.

You can override command/version in plugin config:

```json theme={"dark"}
{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "command": "../acpx/dist/cli.js",
          "expectedVersion": "any"
        }
      }
    }
  }
}
```

Notes:

* `command` accepts an absolute path, relative path, or command name (`acpx`).
* Relative paths resolve from WednesdayAI workspace directory.
* `expectedVersion: "any"` disables strict version matching.
* When `command` points to a custom binary/path, plugin-local auto-install is disabled.
* WednesdayAI startup remains non-blocking while the backend health check runs.

At gateway startup, ACP sessions whose identity is still pending are re-resolved once the backend reports healthy; the gateway waits up to 30 seconds (polling every 250 ms) for the backend to finish starting, then retries each pending session once. If the backend does not become healthy in that window, the reconcile logs a warning and the sessions are not lost: each one re-resolves on its next use.

### Upgrading from acpx 0.1.x

* Persistent ACP sessions created under 0.1.x start a new acpx session on their next use, and the agent's earlier conversation history is not carried over. acpx matches sessions by their exact adapter command, and the default adapters changed (codex → `@agentclientprotocol/codex-acp`, claude → `@agentclientprotocol/claude-agent-acp`, gemini → `gemini --acp`). WednesdayAI re-resolves the session identities automatically at gateway startup.
* Claude sessions no longer load user-level Claude settings (`~/.claude/settings.json`). To restore them, set `ACPX_CLAUDE_INCLUDE_USER_SETTINGS=1` in the gateway's environment; spawned acpx processes inherit it.
* ACP adapter authentication no longer picks up ambient API keys such as `OPENAI_API_KEY`. Set `ACPX_AUTH_<METHOD_ID>` (for example `ACPX_AUTH_OPENAI_API_KEY`) when an adapter needs ACP-level auth.
* Session status reports `idle`, not `dead`, for a resumable session with no running process.
* The first prompt after the upgrade downloads the new adapter through `npx`, so it takes noticeably longer.

See [Plugins](https://docs.wednesdayai.dev/next/users/tools/plugin.md).

## Permission configuration

ACP sessions run non-interactively — there is no TTY to approve or deny file-write and shell-exec permission prompts. The acpx plugin provides two config keys that control how permissions are handled:

### `permissionMode`

Controls which operations the harness agent can perform without prompting.

| Value | Behavior |
| - | - |
| `approve-all` | Auto-approve all file writes and shell commands. |
| `approve-reads` | Auto-approve reads only; writes and exec require prompts. |
| `deny-all` | Deny all permission prompts. |

### `nonInteractivePermissions`

Controls what happens when a permission prompt would be shown but no interactive TTY is available (which is always the case for ACP sessions).

| Value | Behavior |
| - | - |
| `fail` | Abort the session with `AcpRuntimeError`. **(default)** |
| `deny` | Silently deny the permission and continue (graceful degradation). |

### Configuration

Set via plugin config:

```bash theme={"dark"}
wednesdayai config set plugins.entries.acpx.config.permissionMode approve-all
wednesdayai config set plugins.entries.acpx.config.nonInteractivePermissions fail
```

Restart the gateway after changing these values.

> **Important:** WednesdayAI currently defaults to `permissionMode=approve-reads` and `nonInteractivePermissions=fail`. In non-interactive ACP sessions, any write or exec that triggers a permission prompt can fail with `AcpRuntimeError: Permission prompt unavailable in non-interactive mode`.
>
> If you need to restrict permissions, set `nonInteractivePermissions` to `deny` so sessions degrade gracefully instead of crashing.

## Gateway restarts

ACP turns survive a gateway restart by state, not by process. Each turn is recorded as a `kind: "acp"` session run, so a restart or stop never silently loses one.

What you see as a user:

* If the gateway restarts or stops while an ACP turn is running, the turn is cancelled and the bound thread receives one notice:

  ```text theme={"dark"}
  ACP error (ACP_TURN_INTERRUPTED): The gateway stopped this turn during a restart or shutdown. Commands or edits it started may have completed.
  next: Your ACP session is preserved. Reply after the gateway is back to continue.
  ```

* Commands or edits the harness already started may still have completed even though no final reply arrived. Treat any partial output as a side effect that happened, and review the workspace before re-asking.

* Messages sent while the gateway is restarting never reach the agent, so nothing ran and there are no side effects. The gateway refuses new messages as soon as the restart drain begins, so you may get no reply at all, or an `ACP_GATEWAY_DRAINING` error for a message that arrived just as the drain started. Either way, resend it after the gateway is back.

* If the gateway crashes instead of restarting cleanly, or the notice could not be delivered during the shutdown (this includes turns started by a spawned agent task rather than a message in the thread), the same notice is delivered at the next boot. Once the notice reaches you it is not repeated; if the gateway still could not deliver it (for example the chat channel was still coming back online), it tries again later instead of skipping you.

* A run-mode child (`sessions_spawn` with `mode: "run"`) has no thread of its own. If the gateway restarts during its turn, the requesting agent is told the child ended with an error.

To continue, reply in the same thread after the gateway is back. The reply resumes the same ACP session with its earlier context, and `/acp status` shows the same `agentSessionId`. `sessions.runs.continue` does not apply to ACP turns: continuation is by replying in the bound thread, not through that RPC.

## Troubleshooting

| Symptom | Likely cause | Fix |
| - | - | - |
| `ACP runtime backend is not configured` | Backend plugin missing or disabled. | Install and enable backend plugin, then run `/acp doctor`. |
| `ACP is disabled by policy (acp.enabled=false)` | ACP globally disabled. | Set `acp.enabled=true`. |
| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | Dispatch from normal thread messages disabled. | Set `acp.dispatch.enabled=true`. |
| `ACP agent "<id>" is not allowed by policy` | Agent not in allowlist. | Use allowed `agentId` or update `acp.allowedAgents`. |
| `Unable to resolve session target: ...` | Bad key/id/label token. | Run `/acp sessions`, copy exact key/label, retry. |
| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` used outside a thread context. | Move to target thread or use `--thread auto`/`off`. |
| `Only <user-id> can rebind this thread.` | Another user owns thread binding. | Rebind as owner or use a different thread. |
| `Thread bindings are unavailable for <channel>.` | Adapter lacks thread binding capability. | Use `--thread off` or move to supported adapter/channel. |
| `Sandboxed sessions cannot spawn ACP sessions ...` | ACP runtime is host-side; requester session is sandboxed. | Use `runtime="subagent"` from sandboxed sessions, or run ACP spawn from a non-sandboxed session. |
| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | `sandbox="require"` requested for ACP runtime. | Use `runtime="subagent"` for required sandboxing, or use ACP with `sandbox="inherit"` from a non-sandboxed session. |
| Missing ACP metadata for bound session | Stale/deleted ACP session metadata. | Recreate with `/acp spawn`, then rebind/focus thread. |
| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` blocks writes/exec in non-interactive ACP session. | Set `plugins.entries.acpx.config.permissionMode` to `approve-all` and restart gateway. See [Permission configuration](#permission-configuration). |
| ACP session fails early with little output | Permission prompts are blocked by `permissionMode`/`nonInteractivePermissions`. | Check gateway logs for `AcpRuntimeError`. For full permissions, set `permissionMode=approve-all`; for graceful degradation, set `nonInteractivePermissions=deny`. |
| ACP session stalls indefinitely after completing work | Harness process finished but ACP session did not report completion. | Monitor with `ps aux \| grep acpx`; kill stale processes manually. |
| Long ACP task cut off by a gateway restart (`ACP_TURN_INTERRUPTED`) | Expected restart behavior: the running turn was cancelled and recorded. | See [Gateway restarts](#gateway-restarts). Reply in the bound thread to continue the same session; resend a message rejected with `ACP_GATEWAY_DRAINING` after the gateway is back. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.