fix: stabilize Claude permission mode for unattended loops

- default Claude Code loops to permission-mode auto\n- validate and normalize Claude permission mode config\n- preserve managed .ralphrc upgrades and env precedence

Author: LarsCowe

README.md

@@ -394,7 +394,7 @@ The instructions file and command directory depend on the configured platform. S
 
 Ralph is a bash loop that spawns fresh AI coding sessions using a **platform driver** matching the configured platform:
 
-- **Claude Code driver** — invokes `claude` with `--output-format json`, `--allowedTools`, and explicit `--resume <session_id>`
+- **Claude Code driver** — invokes `claude` with `--output-format json`, `--permission-mode auto`, `--allowedTools`, and explicit `--resume <session_id>`
 - **Codex driver** — invokes `codex exec --json --sandbox workspace-write` with explicit `--resume <session_id>`
 - **Copilot driver** _(experimental)_ — invokes `copilot --autopilot --yolo` with plain-text output
 - **Cursor driver** _(experimental)_ — invokes `cursor-agent -p --force --output-format json`, persists `session_id` for `--resume`, and switches to `stream-json` only for live output
@@ -451,6 +451,9 @@ If you get permission errors:
 # .ralph/.ralphrc
 ALLOWED_TOOLS="Write,Read,Edit,MultiEdit,Glob,Grep,Task,TodoWrite,WebFetch,WebSearch,NotebookEdit,Bash"
 
+# Keep interactive approval workflows out of unattended Claude loops
+CLAUDE_PERMISSION_MODE="auto"
+
 # Keep the loop unattended by continuing after detected denials
 PERMISSION_DENIAL_MODE="continue"
 
@@ -461,7 +464,8 @@ bmalph run
 
 Notes:
 
-- `ALLOWED_TOOLS` only applies to the Claude Code driver.
+- `ALLOWED_TOOLS` only applies to the Claude Code driver and controls normal tool access.
+- `CLAUDE_PERMISSION_MODE="auto"` prevents interactive approval modes like plan approval from blocking unattended Claude loops.
 - Codex, Cursor, and Copilot use their native sandbox/approval settings instead.
 - Fresh installs default to unattended mode and discourage in-loop user questions via `.ralph/PROMPT.md`.
 

ralph/RALPH-REFERENCE.md

@@ -61,6 +61,7 @@ Environment variables > Ralph config file > script defaults
 | `CLAUDE_TIMEOUT_MINUTES` | `15` | Timeout per loop driver invocation |
 | `CLAUDE_OUTPUT_FORMAT` | `json` | Output format (json or text) |
 | `ALLOWED_TOOLS` | `Write,Read,Edit,MultiEdit,Glob,Grep,Task,TodoWrite,WebFetch,WebSearch,NotebookEdit,Bash` | Claude Code only. Ignored by codex, cursor, and copilot |
+| `CLAUDE_PERMISSION_MODE` | `auto` | Claude Code only. Prevents interactive approval workflows from blocking unattended loops |
 | `PERMISSION_DENIAL_MODE` | `continue` | How Ralph responds to permission denials: continue, halt, or threshold |
 | `SESSION_CONTINUITY` | `true` | Maintain context across loops |
 | `SESSION_EXPIRY_HOURS` | `24` | Session expiration time |
@@ -340,9 +341,10 @@ When using `--monitor` with `--live`, tmux creates a 3-pane layout:
 
 **Solutions:**
 1. For Claude Code, update `ALLOWED_TOOLS` in `.ralph/.ralphrc` to include needed tools
-2. For codex, cursor, and copilot, review the driver's native permission settings; `ALLOWED_TOOLS` is ignored
-3. If you want unattended behavior, keep `PERMISSION_DENIAL_MODE="continue"` in `.ralph/.ralphrc`
-4. Reset circuit breaker if needed: `bash .ralph/ralph_loop.sh --reset-circuit`
+2. For Claude Code unattended loops, keep `CLAUDE_PERMISSION_MODE="auto"` in `.ralph/.ralphrc`
+3. For codex, cursor, and copilot, review the driver's native permission settings; `ALLOWED_TOOLS` is ignored
+4. If you want unattended behavior, keep `PERMISSION_DENIAL_MODE="continue"` in `.ralph/.ralphrc`
+5. Reset circuit breaker if needed: `bash .ralph/ralph_loop.sh --reset-circuit`
 
 #### Session expires mid-project
 

ralph/drivers/claude-code.sh

@@ -54,8 +54,10 @@ driver_supports_tool_allowlist() {
 }
 
 driver_permission_denial_help() {
-    echo "  1. Edit $RALPHRC_FILE and update ALLOWED_TOOLS to include the required tools"
-    echo "  2. Common patterns:"
+    echo "  1. Edit $RALPHRC_FILE and keep CLAUDE_PERMISSION_MODE=auto for unattended Claude Code loops"
+    echo "  2. If Claude was denied on an interactive approval step, ALLOWED_TOOLS will not fix it"
+    echo "  3. If Claude was denied on a normal tool, update ALLOWED_TOOLS to include the required tools"
+    echo "  4. Common ALLOWED_TOOLS patterns:"
     echo "     - Bash                - All shell commands"
     echo "     - Bash(node *)        - All Node.js commands"
     echo "     - Bash(npm *)         - All npm commands"
@@ -77,6 +79,7 @@ driver_build_command() {
     local prompt_file=$1
     local loop_context=$2
     local session_id=$3
+    local resolved_permission_mode="${CLAUDE_PERMISSION_MODE:-auto}"
 
     # Note: We do NOT use --dangerously-skip-permissions here. Tool permissions
     # are controlled via --allowedTools from CLAUDE_ALLOWED_TOOLS in .ralphrc.
@@ -93,6 +96,9 @@ driver_build_command() {
         CLAUDE_CMD_ARGS+=("--output-format" "json")
     fi
 
+    # Prevent interactive approval flows from blocking unattended -p loops.
+    CLAUDE_CMD_ARGS+=("--permission-mode" "$resolved_permission_mode")
+
     # Allowed tools
     if [[ -n "$CLAUDE_ALLOWED_TOOLS" ]]; then
         CLAUDE_CMD_ARGS+=("--allowedTools")

ralph/ralph_loop.sh

@@ -40,6 +40,8 @@ _env_MAX_CALLS_PER_HOUR="${MAX_CALLS_PER_HOUR:-}"
 _env_CLAUDE_TIMEOUT_MINUTES="${CLAUDE_TIMEOUT_MINUTES:-}"
 _env_CLAUDE_OUTPUT_FORMAT="${CLAUDE_OUTPUT_FORMAT:-}"
 _env_CLAUDE_ALLOWED_TOOLS="${CLAUDE_ALLOWED_TOOLS:-}"
+_env_has_CLAUDE_PERMISSION_MODE="${CLAUDE_PERMISSION_MODE+x}"
+_env_CLAUDE_PERMISSION_MODE="${CLAUDE_PERMISSION_MODE:-}"
 _env_CLAUDE_USE_CONTINUE="${CLAUDE_USE_CONTINUE:-}"
 _env_CLAUDE_SESSION_EXPIRY_HOURS="${CLAUDE_SESSION_EXPIRY_HOURS:-}"
 _env_ALLOWED_TOOLS="${ALLOWED_TOOLS:-}"
@@ -77,6 +79,7 @@ DEFAULT_PERMISSION_DENIAL_MODE="continue"
 # Modern Claude CLI configuration (Phase 1.1)
 CLAUDE_OUTPUT_FORMAT="${CLAUDE_OUTPUT_FORMAT:-json}"
 CLAUDE_ALLOWED_TOOLS="${CLAUDE_ALLOWED_TOOLS:-$DEFAULT_CLAUDE_ALLOWED_TOOLS}"
+CLAUDE_PERMISSION_MODE="${CLAUDE_PERMISSION_MODE:-auto}"
 CLAUDE_USE_CONTINUE="${CLAUDE_USE_CONTINUE:-true}"
 PERMISSION_DENIAL_MODE="${PERMISSION_DENIAL_MODE:-$DEFAULT_PERMISSION_DENIAL_MODE}"
 CLAUDE_SESSION_FILE="$RALPH_DIR/.claude_session_id" # Session ID persistence file
@@ -158,6 +161,7 @@ resolve_ralphrc_file() {
 #   - MAX_CALLS_PER_HOUR
 #   - CLAUDE_TIMEOUT_MINUTES
 #   - CLAUDE_OUTPUT_FORMAT
+#   - CLAUDE_PERMISSION_MODE
 #   - ALLOWED_TOOLS (mapped to CLAUDE_ALLOWED_TOOLS for Claude Code only)
 #   - PERMISSION_DENIAL_MODE
 #   - SESSION_CONTINUITY (mapped to CLAUDE_USE_CONTINUE)
@@ -203,6 +207,9 @@ load_ralphrc() {
     [[ -n "$_env_CLAUDE_TIMEOUT_MINUTES" ]] && CLAUDE_TIMEOUT_MINUTES="$_env_CLAUDE_TIMEOUT_MINUTES"
     [[ -n "$_env_CLAUDE_OUTPUT_FORMAT" ]] && CLAUDE_OUTPUT_FORMAT="$_env_CLAUDE_OUTPUT_FORMAT"
     [[ -n "$_env_CLAUDE_ALLOWED_TOOLS" ]] && CLAUDE_ALLOWED_TOOLS="$_env_CLAUDE_ALLOWED_TOOLS"
+    if [[ "$_env_has_CLAUDE_PERMISSION_MODE" == "x" ]]; then
+        CLAUDE_PERMISSION_MODE="$_env_CLAUDE_PERMISSION_MODE"
+    fi
     [[ -n "$_env_CLAUDE_USE_CONTINUE" ]] && CLAUDE_USE_CONTINUE="$_env_CLAUDE_USE_CONTINUE"
     [[ -n "$_env_CLAUDE_SESSION_EXPIRY_HOURS" ]] && CLAUDE_SESSION_EXPIRY_HOURS="$_env_CLAUDE_SESSION_EXPIRY_HOURS"
     [[ -n "$_env_PERMISSION_DENIAL_MODE" ]] && PERMISSION_DENIAL_MODE="$_env_PERMISSION_DENIAL_MODE"
@@ -229,6 +236,7 @@ load_ralphrc() {
     [[ -n "$_env_CB_COOLDOWN_MINUTES" ]] && CB_COOLDOWN_MINUTES="$_env_CB_COOLDOWN_MINUTES"
     [[ -n "$_env_CB_AUTO_RESET" ]] && CB_AUTO_RESET="$_env_CB_AUTO_RESET"
 
+    normalize_claude_permission_mode
     RALPHRC_FILE="$config_file"
     RALPHRC_LOADED=true
     return 0
@@ -241,6 +249,7 @@ driver_supports_tool_allowlist() {
 driver_permission_denial_help() {
     echo "  - Review the active driver's permission or approval settings."
     echo "  - ALLOWED_TOOLS in $RALPHRC_FILE only applies to the Claude Code driver."
+    echo "  - Keep CLAUDE_PERMISSION_MODE=auto for unattended Claude Code loops."
     echo "  - After updating permissions, reset the session and restart the loop."
 }
 
@@ -519,6 +528,27 @@ validate_permission_denial_mode() {
     esac
 }
 
+normalize_claude_permission_mode() {
+    if [[ -z "${CLAUDE_PERMISSION_MODE:-}" ]]; then
+        CLAUDE_PERMISSION_MODE="auto"
+    fi
+}
+
+validate_claude_permission_mode() {
+    local mode=$1
+
+    case "$mode" in
+        auto|acceptEdits|bypassPermissions|default|dontAsk|plan)
+            return 0
+            ;;
+        *)
+            echo "Error: Invalid CLAUDE_PERMISSION_MODE: '$mode'"
+            echo "Valid modes: auto acceptEdits bypassPermissions default dontAsk plan"
+            return 1
+            ;;
+    esac
+}
+
 warn_if_allowed_tools_ignored() {
     if driver_supports_tool_allowlist; then
         return 0
@@ -1633,6 +1663,14 @@ main() {
         exit 1
     fi
 
+    if [[ "$(driver_name)" == "claude-code" ]]; then
+        normalize_claude_permission_mode
+
+        if ! validate_claude_permission_mode "$CLAUDE_PERMISSION_MODE"; then
+            exit 1
+        fi
+    fi
+
     if driver_supports_tool_allowlist; then
         # Validate --allowed-tools now that platform-specific VALID_TOOL_PATTERNS are loaded
         if [[ "${_CLI_ALLOWED_TOOLS:-}" == "true" ]] && ! validate_allowed_tools "$CLAUDE_ALLOWED_TOOLS"; then

ralph/templates/ralphrc.template

@@ -45,6 +45,10 @@ CLAUDE_OUTPUT_FORMAT="json"
 # Opt in to interactive pauses by adding AskUserQuestion manually.
 ALLOWED_TOOLS="Write,Read,Edit,MultiEdit,Glob,Grep,Task,TodoWrite,WebFetch,WebSearch,NotebookEdit,Bash"
 
+# Permission mode for Claude Code CLI (default: auto)
+# Options: auto, acceptEdits, bypassPermissions, default, dontAsk, plan
+CLAUDE_PERMISSION_MODE="auto"
+
 # How Ralph responds when a driver reports permission denials:
 # - continue: log the denial and keep looping (default for unattended mode)
 # - halt: stop immediately and show recovery guidance

src/installer/template-files.ts

@@ -9,6 +9,11 @@ const TEMPLATE_PLACEHOLDERS: Record<string, string> = {
 };
 
 const RALPHRC_TEMPLATE_NAME = "RALPHRC";
+const CLAUDE_PERMISSION_MODE_TEMPLATE_BLOCK = `# Permission mode for Claude Code CLI (default: auto)
+# Options: auto, acceptEdits, bypassPermissions, default, dontAsk, plan
+CLAUDE_PERMISSION_MODE="auto"
+
+`;
 
 const LEGACY_RALPHRC_TEMPLATE = `# .ralphrc - Ralph project configuration
 # Generated by: ralph enable
@@ -145,6 +150,14 @@ async function isRalphrcCustomized(filePath: string, platformId: string): Promis
     return false;
   }
 
+  const previousManagedTemplate = currentTemplate.replace(
+    CLAUDE_PERMISSION_MODE_TEMPLATE_BLOCK,
+    ""
+  );
+  if (content === previousManagedTemplate) {
+    return false;
+  }
+
   const legacyTemplate = renderLegacyRalphrcTemplate(platformId);
   return content !== legacyTemplate;
 }

tests/bash/drivers/claude_code.bats

@@ -66,6 +66,19 @@ teardown() {
     [[ "$found_git" == "true" ]]
 }
 
+@test "driver_permission_denial_help distinguishes permission mode from allowed tools" {
+    RALPHRC_FILE="$RALPH_DIR/.ralphrc"
+
+    run driver_permission_denial_help
+
+    assert_success
+    assert_output --partial "CLAUDE_PERMISSION_MODE=auto"
+    assert_output --partial "ALLOWED_TOOLS"
+    assert_output --partial "will not fix it"
+    assert_output --partial "--reset-session"
+    assert_output --partial "bmalph run"
+}
+
 # ===========================================================================
 # driver_build_command
 # ===========================================================================
@@ -93,6 +106,7 @@ teardown() {
 
     export CLAUDE_OUTPUT_FORMAT="json"
     export CLAUDE_ALLOWED_TOOLS=""
+    export CLAUDE_PERMISSION_MODE=""
     export CLAUDE_USE_CONTINUE="false"
 
     driver_build_command "$prompt_file" "" ""
@@ -101,12 +115,43 @@ teardown() {
     [[ "$args_str" =~ "--output-format json" ]]
 }
 
+@test "driver_build_command defaults permission mode to auto" {
+    local prompt_file="$RALPH_DIR/prompt.md"
+    echo "Test prompt" > "$prompt_file"
+
+    export CLAUDE_OUTPUT_FORMAT=""
+    export CLAUDE_ALLOWED_TOOLS=""
+    export CLAUDE_PERMISSION_MODE=""
+    export CLAUDE_USE_CONTINUE="false"
+
+    driver_build_command "$prompt_file" "" ""
+
+    local args_str="${CLAUDE_CMD_ARGS[*]}"
+    [[ "$args_str" =~ "--permission-mode auto" ]]
+}
+
+@test "driver_build_command passes configured permission mode" {
+    local prompt_file="$RALPH_DIR/prompt.md"
+    echo "Test prompt" > "$prompt_file"
+
+    export CLAUDE_OUTPUT_FORMAT=""
+    export CLAUDE_ALLOWED_TOOLS=""
+    export CLAUDE_PERMISSION_MODE="dontAsk"
+    export CLAUDE_USE_CONTINUE="false"
+
+    driver_build_command "$prompt_file" "" ""
+
+    local args_str="${CLAUDE_CMD_ARGS[*]}"
+    [[ "$args_str" =~ "--permission-mode dontAsk" ]]
+}
+
 @test "driver_build_command adds allowed tools" {
     local prompt_file="$RALPH_DIR/prompt.md"
     echo "Test prompt" > "$prompt_file"
 
     export CLAUDE_OUTPUT_FORMAT=""
     export CLAUDE_ALLOWED_TOOLS="Write,Read,Bash"
+    export CLAUDE_PERMISSION_MODE=""
     export CLAUDE_USE_CONTINUE="false"
 
     driver_build_command "$prompt_file" "" ""
@@ -124,6 +169,7 @@ teardown() {
 
     export CLAUDE_OUTPUT_FORMAT=""
     export CLAUDE_ALLOWED_TOOLS=""
+    export CLAUDE_PERMISSION_MODE=""
     export CLAUDE_USE_CONTINUE="true"
 
     driver_build_command "$prompt_file" "" "session-abc-123"
@@ -138,6 +184,7 @@ teardown() {
 
     export CLAUDE_OUTPUT_FORMAT=""
     export CLAUDE_ALLOWED_TOOLS=""
+    export CLAUDE_PERMISSION_MODE=""
     export CLAUDE_USE_CONTINUE="true"
 
     driver_build_command "$prompt_file" "" ""
@@ -152,6 +199,7 @@ teardown() {
 
     export CLAUDE_OUTPUT_FORMAT=""
     export CLAUDE_ALLOWED_TOOLS=""
+    export CLAUDE_PERMISSION_MODE=""
     export CLAUDE_USE_CONTINUE="false"
 
     driver_build_command "$prompt_file" "" "session-abc-123"
@@ -166,6 +214,7 @@ teardown() {
 
     export CLAUDE_OUTPUT_FORMAT=""
     export CLAUDE_ALLOWED_TOOLS=""
+    export CLAUDE_PERMISSION_MODE=""
     export CLAUDE_USE_CONTINUE="false"
 
     driver_build_command "$prompt_file" "Loop 3 context: 2 files changed" ""