docs(coding-agent): documented acp approval mode

Added ACP-specific approval-mode guidance covering config inheritance, yolo launch flags, client permission handling, and headless prompt behavior. Fixes #2900
2026-06-17 18:47:53 +00:00
parent 7251ca16d4
commit 88c883c64a
2 changed files with 30 additions and 0 deletions
@@ -89,6 +89,32 @@ approval: (args) =>
    : "exec";
 ```

+## ACP sessions
+
+ACP (`omp acp`) uses the same settings resolver as normal OMP launches. Global `~/.omp/agent/config.yml` applies, project config for the ACP session `cwd` applies, and any `--config <file>` overlays passed to the ACP server process apply to sessions created by that process.
+
+To auto-approve ACP tool calls, set the mode in global or project config:
+
+```yaml
+tools:
+  approvalMode: yolo
+```
+
+Or launch the ACP server with a runtime override or a one-process config overlay:
+
+```bash
+omp acp --yolo
+omp acp --auto-approve
+omp acp --approval-mode yolo
+omp acp --config ./acp-yolo.yml   # file contains tools.approvalMode: yolo
+```
+
+Precedence is the normal settings precedence: runtime flags (`--approval-mode`, `--auto-approve`, `--yolo`) override `--config` overlays, which override project config, which overrides global config. ACP does not currently define a `session/new`, `session/load`, or `session/resume` approval-policy field, so ACP clients that need per-session yolo should launch a separate `omp acp` process with one of the flags above or with a session-specific `--config` overlay.
+
+`tools.approvalMode: yolo` fully applies to ACP when it is explicitly configured or supplied by a runtime flag. It skips OMP's approval prompts and also skips the ACP client permission gate for `bash`, `edit`, `delete`, and `move` unless `tools.approval.<tool>` is `prompt` or `deny`. The schema default is `yolo`, but default-config ACP sessions still keep the client permission gate; set `tools.approvalMode: yolo` explicitly when the client wants unattended execution.
+
+When ACP approval is required, OMP routes it through the ACP client instead of the terminal TUI. Client-gated `bash`, `edit`, `delete`, and `move` calls use ACP `session/request_permission`; generic approval prompts use form elicitation when the client advertises `elicitation.form`. A rejected, cancelled, or unsupported prompt rejects/cancels the tool call; OMP does not silently allow it.
+
 ## Subagents

 Subagents run headless with `tools.approvalMode: yolo` so they do not stall waiting for UI. The parent `task` approval is the authorization boundary. User `tools.approval.<tool>` settings continue to control whether a tool is allowed, prompted, or blocked.
@@ -2,6 +2,10 @@

 ## [Unreleased]

+### Fixed
+
+- Fixed ACP approval-mode documentation to describe config inheritance, `omp acp --yolo`/`--auto-approve` runtime overrides, client permission precedence, and headless prompt behavior ([#2900](https://github.com/can1357/oh-my-pi/issues/2900)).
+
 ## [16.0.5] - 2026-06-17

 ### Added