@quantumclaw/quantumclaw 2026.3.22

package/docs/tools/acp-agents.md

@@ -0,0 +1,623 @@
+---
+summary: "Use ACP runtime sessions for Pi, Claude Code, Codex, OpenCode, Gemini CLI, and other harness agents"
+read_when:
+  - Running coding harnesses through ACP
+  - Setting up thread-bound ACP sessions on thread-capable channels
+  - Binding Discord channels or Telegram forum topics to persistent ACP sessions
+  - Troubleshooting ACP backend and plugin wiring
+  - Operating /acp commands from chat
+title: "ACP Agents"
+---
+
+# ACP agents
+
+[Agent Client Protocol (ACP)](https://agentclientprotocol.com/) sessions let QuantumClaw run external coding harnesses (for example Pi, Claude Code, Codex, OpenCode, and Gemini CLI) through an ACP backend plugin.
+
+If you ask QuantumClaw in plain language to "run this in Codex" or "start Claude Code in a thread", QuantumClaw 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 QuantumClaw 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 QuantumClaw-native delegated runs.
+
+| Area          | ACP session                           | Sub-agent run                      |
+| ------------- | ------------------------------------- | ---------------------------------- |
+| Runtime       | ACP backend plugin (for example acpx) | QuantumClaw 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](/tools/subagents).
+
+## Thread-bound sessions (channel-agnostic)
+
+When thread bindings are enabled for a channel adapter, ACP sessions can be bound to threads:
+
+- QuantumClaw 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, QuantumClaw 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`
+  - Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true`
+
+### Thread supporting channels
+
+- Any channel adapter that exposes session/thread binding capability.
+- Current built-in support:
+  - Discord threads/channels
+  - Telegram topics (forum topics in groups/supergroups and DM topics)
+- Plugin channels can add support through the same binding interface.
+
+## Channel specific settings
+
+For non-ephemeral workflows, configure persistent ACP bindings in top-level `bindings[]` entries.
+
+### Binding model
+
+- `bindings[].type="acp"` marks a persistent ACP conversation binding.
+- `bindings[].match` identifies the target conversation:
+  - Discord channel or thread: `match.channel="discord"` + `match.peer.id="<channelOrThreadId>"`
+  - Telegram forum topic: `match.channel="telegram"` + `match.peer.id="<chatId>:topic:<topicId>"`
+- `bindings[].agentId` is the owning QuantumClaw agent id.
+- Optional ACP overrides live under `bindings[].acp`:
+  - `mode` (`persistent` or `oneshot`)
+  - `label`
+  - `cwd`
+  - `backend`
+
+### Runtime defaults per agent
+
+Use `agents.list[].runtime` to define ACP defaults once per agent:
+
+- `agents.list[].runtime.type="acp"`
+- `agents.list[].runtime.acp.agent` (harness id, for example `codex` or `claude`)
+- `agents.list[].runtime.acp.backend`
+- `agents.list[].runtime.acp.mode`
+- `agents.list[].runtime.acp.cwd`
+
+Override precedence for ACP bound sessions:
+
+1. `bindings[].acp.*`
+2. `agents.list[].runtime.acp.*`
+3. global ACP defaults (for example `acp.backend`)
+
+Example:
+
+```json5
+{
+  agents: {
+    list: [
+      {
+        id: "codex",
+        runtime: {
+          type: "acp",
+          acp: {
+            agent: "codex",
+            backend: "acpx",
+            mode: "persistent",
+            cwd: "/workspace/quantumclaw",
+          },
+        },
+      },
+      {
+        id: "claude",
+        runtime: {
+          type: "acp",
+          acp: { agent: "claude", backend: "acpx", mode: "persistent" },
+        },
+      },
+    ],
+  },
+  bindings: [
+    {
+      type: "acp",
+      agentId: "codex",
+      match: {
+        channel: "discord",
+        accountId: "default",
+        peer: { kind: "channel", id: "222222222222222222" },
+      },
+      acp: { label: "codex-main" },
+    },
+    {
+      type: "acp",
+      agentId: "claude",
+      match: {
+        channel: "telegram",
+        accountId: "default",
+        peer: { kind: "group", id: "-1001234567890:topic:42" },
+      },
+      acp: { cwd: "/workspace/repo-b" },
+    },
+    {
+      type: "route",
+      agentId: "main",
+      match: { channel: "discord", accountId: "default" },
+    },
+    {
+      type: "route",
+      agentId: "main",
+      match: { channel: "telegram", accountId: "default" },
+    },
+  ],
+  channels: {
+    discord: {
+      guilds: {
+        "111111111111111111": {
+          channels: {
+            "222222222222222222": { requireMention: false },
+          },
+        },
+      },
+    },
+    telegram: {
+      groups: {
+        "-1001234567890": {
+          topics: { "42": { requireMention: false } },
+        },
+      },
+    },
+  },
+}
+```
+
+Behavior:
+
+- QuantumClaw ensures the configured ACP session exists before use.
+- Messages in that channel or topic route to the configured ACP session.
+- In bound conversations, `/new` and `/reset` reset the same ACP session key in place.
+- Temporary runtime bindings (for example created by thread-focus flows) still apply where present.
+
+## Start ACP sessions (interfaces)
+
+### From `sessions_spawn`
+
+Use `runtime: "acp"` to start an ACP session from an agent turn or tool call.
+
+```json
+{
+  "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, QuantumClaw uses `acp.defaultAgent` when configured.
+- `mode: "session"` requires `thread: true` to keep a persistent bound conversation.
+
+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, QuantumClaw 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.
+- `resumeSessionId` (optional): resume an existing ACP session instead of creating a new one. The agent replays its conversation history via `session/load`. Requires `runtime: "acp"`.
+- `streamTo` (optional): `"parent"` streams initial ACP run progress summaries back to the requester session as system events.
+  - When available, accepted responses include `streamLogPath` pointing to a session-scoped JSONL log (`<sessionId>.acp-stream.jsonl`) you can tail for full relay history.
+
+### Resume an existing session
+
+Use `resumeSessionId` to continue a previous ACP session instead of starting fresh. The agent replays its conversation history via `session/load`, so it picks up with full context of what came before.
+
+```json
+{
+  "task": "Continue where we left off — fix the remaining test failures",
+  "runtime": "acp",
+  "agentId": "codex",
+  "resumeSessionId": "<previous-session-id>"
+}
+```
+
+Common use cases:
+
+- Hand off a Codex session from your laptop to your phone — tell your agent to pick up where you left off
+- Continue a coding session you started interactively in the CLI, now headlessly through your agent
+- Pick up work that was interrupted by a gateway restart or idle timeout
+
+Notes:
+
+- `resumeSessionId` requires `runtime: "acp"` — returns an error if used with the sub-agent runtime.
+- `resumeSessionId` restores the upstream ACP conversation history; `thread` and `mode` still apply normally to the new QuantumClaw session you are creating, so `mode: "session"` still requires `thread: true`.
+- The target agent must support `session/load` (Codex and Claude Code do).
+- If the session ID isn't found, the spawn fails with a clear error — no silent fallback to a new session.
+
+### Operator smoke test
+
+Use this after a gateway deploy when you want a quick live check that ACP spawn
+is actually working end-to-end, not just passing unit tests.
+
+Recommended gate:
+
+1. Verify the deployed gateway version/commit on the target host.
+2. Confirm the deployed source includes the ACP lineage acceptance in
+   `src/gateway/sessions-patch.ts` (`subagent:* or acp:* sessions`).
+3. Open a temporary ACPX bridge session to a live agent (for example
+   `razor(main)` on `jpclawhq`).
+4. Ask that agent to call `sessions_spawn` with:
+   - `runtime: "acp"`
+   - `agentId: "codex"`
+   - `mode: "run"`
+   - task: `Reply with exactly LIVE-ACP-SPAWN-OK`
+5. Verify the agent reports:
+   - `accepted=yes`
+   - a real `childSessionKey`
+   - no validator error
+6. Clean up the temporary ACPX bridge session.
+
+Example prompt to the live agent:
+
+```text
+Use the sessions_spawn tool now with runtime: "acp", agentId: "codex", and mode: "run".
+Set the task to: "Reply with exactly LIVE-ACP-SPAWN-OK".
+Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exact text or none>.
+```
+
+Notes:
+
+- Keep this smoke test on `mode: "run"` unless you are intentionally testing
+  thread-bound persistent ACP sessions.
+- Do not require `streamTo: "parent"` for the basic gate. That path depends on
+  requester/session capabilities and is a separate integration check.
+- Treat thread-bound `mode: "session"` testing as a second, richer integration
+  pass from a real Discord thread or Telegram topic.
+
+## Sandbox compatibility
+
+ACP sessions currently run on the host runtime, not inside the QuantumClaw sandbox.
+
+Current limitations:
+
+- If the requester session is sandboxed, ACP spawns are blocked for both `sessions_spawn({ runtime: "acp" })` and `/acp spawn`.
+  - 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
+/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](/tools/slash-commands).
+
+## 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, QuantumClaw 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:
+  - Discord: `channels.discord.threadBindings.spawnAcpSessions=true`
+  - Telegram: `channels.telegram.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, QuantumClaw 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-6`                         |
+| `/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`                                                 |
+
+`/acp sessions` reads the store for the current bound or requester session. Commands that accept `session-key`, `session-id`, or `session-label` tokens resolve targets through gateway session discovery, including custom per-agent `session.store` roots.
+
+## 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 QuantumClaw 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 QuantumClaw `agentId` path).
+
+## Required config
+
+Core ACP baseline:
+
+```json5
+{
+  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
+{
+  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](/gateway/configuration-reference).
+
+## Plugin setup for acpx backend
+
+Install and enable plugin:
+
+```bash
+quantumclaw plugins install @quantumclaw/acpx-plugin
+quantumclaw config set plugins.entries.acpx.enabled true
+```
+
+Local workspace install during development:
+
+```bash
+quantumclaw plugins install ./extensions/acpx
+```
+
+Then verify backend health:
+
+```text
+/acp doctor
+```
+
+### acpx command and version configuration
+
+By default, the acpx backend plugin package (`@quantumclaw/acpx-plugin`) uses the plugin-local pinned binary:
+
+1. Command defaults to `extensions/acpx/node_modules/.bin/acpx`.
+2. Expected version defaults to the extension pin.
+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
+{
+  "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 QuantumClaw workspace directory.
+- `expectedVersion: "any"` disables strict version matching.
+- When `command` points to a custom binary/path, plugin-local auto-install is disabled.
+- QuantumClaw startup remains non-blocking while the backend health check runs.
+
+See [Plugins](/tools/plugin).
+
+## 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
+quantumclaw config set plugins.entries.acpx.config.permissionMode approve-all
+quantumclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail
+```
+
+Restart the gateway after changing these values.
+
+> **Important:** QuantumClaw 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.
+
+## 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.                                                                                                |