fix: allow permissionMode to override yolo in claude_code provider (#322)

* fix: allow permissionMode to override yolo in claude_code provider

When running as root/sudo, Claude Code refuses --dangerously-skip-permissions.
The yolo mode was unconditionally passing that flag, causing initialization to fail.
This change lets profile.permissionMode take precedence over yolo, so users can
configure 'auto' or 'bypassPermissions' to avoid the blocked flag.

* fix: update test to match permissionMode-over-yolo behavior

* fix(claude_code): only omit --dangerously-skip-permissions for yolo+root, not all yolo

Previously the elif-yolo branch dropped --dangerously-skip-permissions for every
yolo launch (allowedTools=["*"]), which broke non-root headless sessions by letting
Claude prompt for tool approval inside tmux panes and silently block handoff/assign.

Fix: add is_root guard so the flag is only omitted when running as root/sudo.
Priority order:
  1. profile.permissionMode set  => claude --permission-mode <value>
  2. yolo + is_root              => claude  (flag rejected by Claude under root)
  3. everything else             => claude --dangerously-skip-permissions

Also adds three regression tests covering yolo/non-root, yolo/root, and
yolo+permissionMode to address the Codecov patch coverage warning.

Updates docs/claude-code.md and docs/agent-profile.md to reflect correct priority
(permissionMode > yolo, root-only omission).

Fixes: #322

* fix(claude_code): import os in claude_code.py to avoid NameError

Author: zz327455573

docs/agent-profile.md

@@ -32,7 +32,7 @@ Define the agent's role, responsibilities, and behavior here.
 - `toolAliases` (object): Map tool names to aliases
 - `toolsSettings` (object): Tool-specific configuration
 - `model` (string): AI model to use
-- `permissionMode` (string, `claude_code` only): One of `"default"`, `"acceptEdits"`, `"plan"`, `"auto"`, `"bypassPermissions"`. When set, the `claude_code` provider passes `--permission-mode <value>` instead of `--dangerously-skip-permissions`. `cao launch --yolo` overrides this and forces bypass. See [Claude Code permission modes](https://code.claude.com/docs/en/permission-modes).
+- `permissionMode` (string, `claude_code` only): One of `"default"`, `"acceptEdits"`, `"plan"`, `"auto"`, `"bypassPermissions"`. When set, the `claude_code` provider passes `--permission-mode <value>` instead of `--dangerously-skip-permissions`. `permissionMode` takes priority over `--yolo`; the provider always uses `--permission-mode <value>` when the field is set. See [Claude Code permission modes](https://code.claude.com/docs/en/permission-modes).
 - `native_agent` (string, `claude_code` only): Name of a native Claude Code agent (`~/.claude/agents/`). When set, the provider passes `--agent <name>` directly and skips system prompt / MCP config decomposition (thin-wrapper mode). See [Claude Code native agent routing](claude-code.md#native-agent-routing).
 - `codexProfile` (string, `codex` only): Names a `[profiles.<name>]` block in `~/.codex/config.toml`. When set, the provider drops `--yolo` and passes `--profile <name>` instead. See [Custom Codex Profile](codex-cli.md#custom-codex-profile).
 - `codexConfig` (object, `codex` only): Inline Codex config overrides passed as `-c key=value` at launch (e.g. `model_reasoning_effort`, `service_tier`, `features.fast_mode`). Keys may be dotted config paths; values become TOML scalars. See [Inline Codex Config Overrides](codex-cli.md#inline-codex-config-overrides).

docs/claude-code.md

@@ -67,7 +67,7 @@ By default, CAO launches Claude Code with `--dangerously-skip-permissions` to by
 
 This is safe because CAO already confirms workspace trust during `cao launch` ("Do you trust all the actions in this folder?") or via `--yolo` flag. Without this flag, worker agents spawned via handoff/assign would block on the trust dialog with no way to accept it interactively.
 
-Profiles can opt into a stricter behavior by setting the `permissionMode` field, which causes the provider to pass `--permission-mode <value>` instead of `--dangerously-skip-permissions`. See [Permission Mode Override](#permission-mode-override) below. `cao launch --yolo` always forces `--dangerously-skip-permissions` regardless of the profile's `permissionMode`.
+Profiles can opt into a stricter behavior by setting the `permissionMode` field, which causes the provider to pass `--permission-mode <value>` instead of `--dangerously-skip-permissions`. See [Permission Mode Override](#permission-mode-override) below. `permissionMode` takes priority over `--yolo`; when set, the provider always uses `--permission-mode <value>` regardless of yolo. When running as root/sudo, `--dangerously-skip-permissions` is omitted even in yolo mode because Claude Code rejects it under root.
 
 A fallback `_handle_trust_prompt()` method also monitors for the trust dialog and sends Enter to accept it, in case the flag doesn't cover all scenarios.
 
@@ -97,7 +97,7 @@ The `permissionMode` field on an agent profile lets you replace the default `--d
 
 Allowed values: `default`, `acceptEdits`, `plan`, `auto`, `bypassPermissions`. See the [Claude Code permission modes reference](https://code.claude.com/docs/en/permission-modes) for what each tier does.
 
-When set, the provider passes `--permission-mode <value>` instead of `--dangerously-skip-permissions`. `cao launch --yolo` always overrides this field and forces `--dangerously-skip-permissions` regardless of the profile setting.
+When set, the provider passes `--permission-mode <value>` instead of `--dangerously-skip-permissions`. `permissionMode` takes priority over `--yolo`; the provider always uses `--permission-mode <value>` when the field is set, even in yolo mode.
 
 Example — a reviewer that runs under the `auto` permission classifier instead of unconditional bypass:
 

src/cli_agent_orchestrator/providers/claude_code.py

@@ -2,6 +2,7 @@
 
 import json
 import logging
+import os
 import re
 import shlex
 import time
@@ -165,9 +166,20 @@ def _build_claude_command(self) -> str:
             except Exception as e:
                 raise ProviderError(f"Failed to load agent profile '{self._agent_profile}': {e}")
 
-        # Determine permission mode for the base command
-        if profile and profile.permissionMode and not yolo:
+        # Determine permission mode for the base command.
+        # Priority: explicit permissionMode > yolo/root detection > default yolo.
+        #
+        # Root/sudo guard: Claude Code rejects --dangerously-skip-permissions when
+        # running as root. We only omit it for yolo+root; non-root yolo still needs
+        # the flag so Claude won't prompt for tool approval inside a headless tmux
+        # pane and silently block handoff/assign flows.
+        is_root = getattr(os, "geteuid", lambda: -1)() == 0
+
+        if profile and profile.permissionMode:
             command_parts = ["claude", "--permission-mode", profile.permissionMode]
+        elif yolo and is_root:
+            # Root users cannot use --dangerously-skip-permissions; omit it entirely.
+            command_parts = ["claude"]
         else:
             command_parts = ["claude", "--dangerously-skip-permissions"]
 

test/providers/test_claude_code_unit.py

@@ -1244,7 +1244,7 @@ def test_uses_permission_mode_when_set_and_not_yolo(self, mock_load):
         assert "--dangerously-skip-permissions" not in command
 
     @patch("cli_agent_orchestrator.providers.claude_code.load_agent_profile")
-    def test_yolo_overrides_permission_mode(self, mock_load):
+    def test_permission_mode_takes_priority_over_yolo(self, mock_load):
         mock_profile = MagicMock()
         mock_profile.model = None
         mock_profile.system_prompt = None
@@ -1255,8 +1255,8 @@ def test_yolo_overrides_permission_mode(self, mock_load):
         provider = ClaudeCodeProvider("tid", "sess", "win", "agent", allowed_tools=["*"])
         command = provider._build_claude_command()
 
-        assert "--dangerously-skip-permissions" in command
-        assert "--permission-mode" not in command
+        assert "--permission-mode auto" in command
+        assert "--dangerously-skip-permissions" not in command
 
     @patch("cli_agent_orchestrator.providers.claude_code.load_agent_profile")
     def test_legacy_profile_without_permission_mode(self, mock_load):
@@ -1274,6 +1274,68 @@ def test_legacy_profile_without_permission_mode(self, mock_load):
         assert "--permission-mode" not in command
 
 
+class TestClaudeCodeProviderYoloRootRegression:
+    """Regression tests for yolo + root/non-root --dangerously-skip-permissions logic.
+
+    Ensures that the root-user guard (PR #322) only omits --dangerously-skip-permissions
+    when running as root, and does not break normal non-root yolo launches.
+    """
+
+    @patch("cli_agent_orchestrator.providers.claude_code.load_agent_profile")
+    @patch("cli_agent_orchestrator.providers.claude_code.os")
+    def test_yolo_non_root_includes_dangerously_skip_permissions(self, mock_os, mock_load):
+        """yolo + no permissionMode + non-root => includes --dangerously-skip-permissions."""
+        mock_os.geteuid.return_value = 1000  # non-root
+        mock_profile = MagicMock()
+        mock_profile.model = None
+        mock_profile.system_prompt = None
+        mock_profile.mcpServers = None
+        mock_profile.permissionMode = None
+        mock_load.return_value = mock_profile
+
+        provider = ClaudeCodeProvider("tid", "sess", "win", "agent", allowed_tools=["*"])
+        command = provider._build_claude_command()
+
+        assert "--dangerously-skip-permissions" in command
+        assert "--permission-mode" not in command
+
+    @patch("cli_agent_orchestrator.providers.claude_code.load_agent_profile")
+    @patch("cli_agent_orchestrator.providers.claude_code.os")
+    def test_yolo_root_omits_dangerously_skip_permissions(self, mock_os, mock_load):
+        """yolo + no permissionMode + root => omits --dangerously-skip-permissions."""
+        mock_os.geteuid.return_value = 0  # root
+        mock_profile = MagicMock()
+        mock_profile.model = None
+        mock_profile.system_prompt = None
+        mock_profile.mcpServers = None
+        mock_profile.permissionMode = None
+        mock_load.return_value = mock_profile
+
+        provider = ClaudeCodeProvider("tid", "sess", "win", "agent", allowed_tools=["*"])
+        command = provider._build_claude_command()
+
+        assert "--dangerously-skip-permissions" not in command
+        assert "--permission-mode" not in command
+
+    @patch("cli_agent_orchestrator.providers.claude_code.load_agent_profile")
+    @patch("cli_agent_orchestrator.providers.claude_code.os")
+    def test_yolo_with_permission_mode_uses_permission_mode_flag(self, mock_os, mock_load):
+        """yolo + permissionMode => uses --permission-mode <value>, omits --dangerously-skip-permissions."""
+        mock_os.geteuid.return_value = 1000  # non-root; permissionMode should still win
+        mock_profile = MagicMock()
+        mock_profile.model = None
+        mock_profile.system_prompt = None
+        mock_profile.mcpServers = None
+        mock_profile.permissionMode = "auto"
+        mock_load.return_value = mock_profile
+
+        provider = ClaudeCodeProvider("tid", "sess", "win", "agent", allowed_tools=["*"])
+        command = provider._build_claude_command()
+
+        assert "--permission-mode auto" in command
+        assert "--dangerously-skip-permissions" not in command
+
+
 class TestClaudeCodeProviderStartupPrompts:
     """Tests for Claude Code startup prompt handling (trust + bypass)."""