fix(launch): clarify prompt, add --auto-approve, document TOOL_MAPPING (#146)

* fix(launch): clarify confirmation prompt — show Role, remove Blocked, distinguish Y vs --yolo

The launch confirmation prompt was misleading: it showed "Blocked: (none)" for
providers that enforce restrictions natively (kiro-cli, q-cli), and the --yolo
hint didn't make clear that users need to exit and re-run. Now the prompt shows
Role and Allowed in CAO vocabulary, and clearly explains that [Y] keeps
restrictions while [--yolo] overrides everything.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat(launch): add --auto-approve flag to skip confirmation prompt

Adds --auto-approve to skip the confirmation prompt while keeping tool
restrictions enforced. Useful for automated flows, scripted launches,
and agent-to-agent workflows where --yolo is too permissive.

Addresses review feedback on PR #146 re: automated flows hanging on
the Y/n prompt.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: clarify TOOL_MAPPING role and why only 3 providers need it

Rewrite the "How Tool Restrictions Are Enforced" section to explain
why TOOL_MAPPING only covers Claude Code, Copilot CLI, and Gemini CLI
(they need translation to native tool names), while Kiro CLI, Q CLI,
Kimi CLI, and Codex accept CAO vocabulary directly.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(launch): clarify prompt hints — say "relaunch with" not bracket options

The prompt hints like [--auto-approve] and [--yolo] implied users could
type them at the Y/n prompt. Changed to "relaunch with --auto-approve"
and "relaunch with --yolo" to make clear these are CLI flags for the
next launch, not options at the current prompt.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: haofeif

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **Launch prompt clarity + `--auto-approve`** — Redesign the `cao launch` confirmation prompt to show `Role` instead of `Blocked`, clearly distinguish `[Y]` / `[--auto-approve]` / `[--yolo]`, and add `--auto-approve` flag to skip the prompt without removing restrictions (for automated flows, scripts, and agent-to-agent launches)
+
 ### Fixed
 
 - **Kiro CLI new TUI support** — Add fallback detection patterns for the new Kiro CLI TUI prompt format (`ask a question, or describe a task`), ensuring CAO works even if `--legacy-ui` is removed in a future version

README.md

@@ -504,8 +504,9 @@ role: supervisor  # @cao-mcp-server, fs_read, fs_list
 ```
 
 ```bash
-cao launch --agents code_supervisor              # Uses role defaults
-cao launch --agents code_supervisor --yolo       # Unrestricted access (WARNING shown)
+cao launch --agents code_supervisor                  # Uses role defaults (confirmation prompt shown)
+cao launch --agents code_supervisor --auto-approve   # Skip prompt (restrictions still enforced)
+cao launch --agents code_supervisor --yolo           # Unrestricted access (WARNING shown)
 ```
 
 For the full reference — roles, tool vocabulary, custom roles, launch prompts, provider enforcement, and known limitations — see [docs/tool-restrictions.md](docs/tool-restrictions.md).

docs/tool-restrictions.md

@@ -135,15 +135,16 @@ A warning is still displayed so you know what's happening:
 
 ## Launch Confirmation Prompt
 
-When you run `cao launch` without `--yolo`, CAO shows a summary of the resolved tool restrictions and asks for confirmation:
+When you run `cao launch` without `--yolo` or `--auto-approve`, CAO shows a summary of the resolved tool restrictions and asks for confirmation:
 
 ```
 Agent 'code_supervisor' launching on kiro_cli:
-  Allowed:  @cao-mcp-server, fs_read, fs_list
-  Blocked:  Bash, Edit, Write
+  Role:      supervisor
+  Allowed:   @cao-mcp-server, fs_read, fs_list
   Directory: /home/user/my-project
 
-  To grant all permissions, re-run with --yolo.
+  To skip this prompt next time, relaunch with --auto-approve
+  To remove all restrictions, relaunch with --yolo
 
 Proceed? [Y/n]
 ```
@@ -152,30 +153,50 @@ If no `role` or `allowedTools` is set in the profile, the prompt includes an add
 
 ```
 Agent 'my_agent' launching on claude_code:
-  Allowed:  @builtin, fs_*, execute_bash, @cao-mcp-server
-  Blocked:  (none)
+  Role:      (not set — using developer defaults)
+  Allowed:   @builtin, fs_*, execute_bash, @cao-mcp-server
   Directory: /home/user/my-project
 
   Note: No role or allowedTools set — defaulting to 'developer'.
   Add 'role' or 'allowedTools' to your agent profile to control tool access.
   Docs: https://github.com/awslabs/cli-agent-orchestrator/blob/main/docs/tool-restrictions.md
 
-  To grant all permissions, re-run with --yolo.
+  To skip this prompt next time, relaunch with --auto-approve
+  To remove all restrictions, relaunch with --yolo
 
 Proceed? [Y/n]
 ```
 
-### Confirmation vs `--yolo`
+### `--auto-approve` vs `--yolo`
 
-Answering **Y** to the confirmation prompt is **not** the same as `--yolo`:
+| | `Y` at prompt | `--auto-approve` | `--yolo` |
+|---|---|---|---|
+| **Confirmation prompt** | Shown | Skipped | Skipped |
+| **Tool restrictions** | Enforced | Enforced | Removed — `["*"]` |
+| **Use case** | Interactive launch | Automated flows, scripts, agent-to-agent | Unrestricted access |
 
-| | Confirmation → Y | `--yolo` |
-|---|---|---|
-| **Tool restrictions** | Still enforced — agent is limited to the tools shown in "Allowed" | Removed — agent gets `["*"]` (all tools) |
-| **Blocked tools** | Still blocked — agent cannot use tools shown in "Blocked" | Nothing is blocked |
-| **What it means** | "I've reviewed these restrictions and want to proceed" | "Give the agent unrestricted access, no questions asked" |
+```bash
+cao launch --agents my_agent                  # interactive — shows prompt
+cao launch --agents my_agent --auto-approve   # automated — skips prompt, keeps restrictions
+cao launch --agents my_agent --yolo           # unrestricted — skips prompt AND removes restrictions
+```
+
+The confirmation prompt is a **review gate** — it shows the resolved role and allowed tools, then lets you proceed or cancel. `--auto-approve` skips this gate while keeping all restrictions enforced — useful for CAO flows, scripted launches, and agent-to-agent workflows. `--yolo` sits at the top of the override hierarchy — it **overrides both role and allowedTools**, grants unrestricted access (`["*"]`), and skips the prompt entirely.
+
+### How Tool Restrictions Are Enforced (Implementation Detail)
+
+CAO defines a universal tool vocabulary (`execute_bash`, `fs_read`, `fs_write`, `fs_list`). However, not all providers understand this vocabulary natively. There are two categories:
 
-The confirmation prompt is a **review gate** — it shows you exactly what the agent can and cannot do, then lets you proceed or cancel. The restrictions listed in the summary are still enforced after you confirm. `--yolo` both **removes all restrictions** and **skips the review gate entirely**.
+**Providers that need translation** — Claude Code, Copilot CLI, and Gemini CLI each have their own native tool names (e.g., Claude Code calls bash execution `Bash`, Copilot calls it `shell`). CAO uses an internal `TOOL_MAPPING` to translate the CAO vocabulary to provider-native names, then computes which native tools to block and passes them as CLI flags (e.g., `--disallowedTools Bash`, `--deny-tool shell`).
+
+| CAO Tool | Claude Code | Copilot CLI | Gemini CLI |
+|----------|-------------|-------------|------------|
+| `execute_bash` | `Bash` | `shell` | `run_shell_command` |
+| `fs_read` | `Read` | `read` | `read_file`, `list_directory`, `search_file_content`, `glob` |
+| `fs_write` | `Edit`, `Write` | `write` | `write_file`, `replace` |
+| `fs_list` | `Glob`, `Grep` | `list`, `grep` | `list_directory`, `glob`, `search_file_content` |
+
+**Providers that accept CAO vocabulary directly** — Kiro CLI and Q CLI accept `allowedTools` in the agent JSON at install time, using the same vocabulary as CAO. No translation needed. Kimi CLI and Codex use system prompt instructions to enforce restrictions. For all four, CAO passes the `allowedTools` list directly without translation — so no `TOOL_MAPPING` entry exists for them, and none is needed.
 
 ## How Overrides Work
 
@@ -191,12 +212,17 @@ Priority (highest to lowest):
   5. (nothing set)             → developer defaults
 ```
 
+Note: `--auto-approve` is **not** in this priority chain — it only controls whether the confirmation prompt is shown, not what restrictions are applied.
+
 Examples:
 
 ```bash
 # Profile has role: supervisor → restricted to @cao-mcp-server + fs_read + fs_list
 cao launch --agents code_supervisor
 
+# Same, but skip the confirmation prompt (restrictions still enforced)
+cao launch --agents code_supervisor --auto-approve
+
 # CLI flag overrides the role
 cao launch --agents code_supervisor --allowed-tools execute_bash --allowed-tools fs_read
 
@@ -206,7 +232,7 @@ cao launch --agents code_supervisor --yolo
 
 ## Provider Enforcement
 
-CAO translates `allowedTools` to each provider's native restriction mechanism:
+As described in [How Tool Restrictions Are Enforced](#how-tool-restrictions-are-enforced-implementation-detail), some providers require CAO to translate `allowedTools` to native tool names (via `TOOL_MAPPING`), while others accept the CAO vocabulary directly. The table below shows how each provider enforces restrictions:
 
 | Provider | Enforcement | How it works |
 |----------|------------|-------------|
@@ -281,8 +307,9 @@ Each agent is restricted based on its own profile, not its parent's permissions.
 | Custom tool set | `allowedTools: ["fs_read", "execute_bash"]` |
 | Reusable custom preset | Define in `settings.json` `roles`, use `role: my_preset` |
 | Override role at launch | `--allowed-tools fs_read --allowed-tools @cao-mcp-server` |
-| No restrictions at all | `--yolo` or don't set role/allowedTools |
-| Check what's allowed before launch | Launch without `--yolo` — the confirmation prompt shows the summary |
+| Skip confirmation in scripts/automation | `--auto-approve` (restrictions still enforced) |
+| No restrictions at all | `--yolo` |
+| Check what's allowed before launch | Launch without `--yolo` or `--auto-approve` — the prompt shows the summary |
 
 ## Security Recommendations
 

src/cli_agent_orchestrator/cli/commands/launch.py

@@ -31,13 +31,18 @@
     multiple=True,
     help="Override allowedTools (CAO format: execute_bash, fs_read, @cao-mcp-server). Repeatable.",
 )
+@click.option(
+    "--auto-approve",
+    is_flag=True,
+    help="Skip confirmation prompt (restrictions still enforced).",
+)
 @click.option(
     "--yolo",
     is_flag=True,
     help="[DANGEROUS] Unrestricted tool access AND skip confirmation prompts. "
     "Agent can execute ANY command including aws, rm, curl.",
 )
-def launch(agents, session_name, headless, provider, allowed_tools, yolo):
+def launch(agents, session_name, headless, provider, allowed_tools, auto_approve, yolo):
     """Launch cao session with specified agent profile."""
     try:
         # Validate provider
@@ -51,12 +56,12 @@ def launch(agents, session_name, headless, provider, allowed_tools, yolo):
         from cli_agent_orchestrator.utils.agent_profiles import load_agent_profile
         from cli_agent_orchestrator.utils.tool_mapping import (
             format_tool_summary,
-            get_disallowed_tools,
             resolve_allowed_tools,
         )
 
         resolved_allowed_tools = None
         no_role_set = False
+        resolved_role = None
         if yolo:
             resolved_allowed_tools = ["*"]
         elif allowed_tools:
@@ -67,6 +72,7 @@ def launch(agents, session_name, headless, provider, allowed_tools, yolo):
                 profile = load_agent_profile(agents)
                 mcp_server_names = list(profile.mcpServers.keys()) if profile.mcpServers else None
                 no_role_set = not profile.role and not profile.allowedTools
+                resolved_role = profile.role
                 resolved_allowed_tools = resolve_allowed_tools(
                     profile.allowedTools, profile.role, mcp_server_names
                 )
@@ -88,13 +94,14 @@ def launch(agents, session_name, headless, provider, allowed_tools, yolo):
             else:
                 # Normal launch: show tool summary and confirm
                 tool_summary = format_tool_summary(resolved_allowed_tools)
-                blocked = get_disallowed_tools(provider, resolved_allowed_tools)
-                blocked_summary = ", ".join(blocked) if blocked else "(none)"
+                role_display = (
+                    resolved_role if resolved_role else "(not set — using developer defaults)"
+                )
 
                 click.echo(
                     f"\nAgent '{agents}' launching on {provider}:\n"
-                    f"  Allowed:  {tool_summary}\n"
-                    f"  Blocked:  {blocked_summary}\n"
+                    f"  Role:      {role_display}\n"
+                    f"  Allowed:   {tool_summary}\n"
                     f"  Directory: {working_directory}\n"
                 )
                 if no_role_set:
@@ -103,8 +110,11 @@ def launch(agents, session_name, headless, provider, allowed_tools, yolo):
                         "  Add 'role' or 'allowedTools' to your agent profile to control tool access.\n"
                         "  Docs: https://github.com/awslabs/cli-agent-orchestrator/blob/main/docs/tool-restrictions.md\n"
                     )
-                click.echo("  To grant all permissions, re-run with --yolo.\n")
-                if not click.confirm("Proceed?", default=True):
+                click.echo(
+                    "  To skip this prompt next time, relaunch with --auto-approve\n"
+                    "  To remove all restrictions, relaunch with --yolo\n"
+                )
+                if not auto_approve and not click.confirm("Proceed?", default=True):
                     raise click.ClickException("Launch cancelled by user")
 
         # Call API to create session