investigate: Bash wildcard patterns in ALLOWED_TOOLS not working

[frankbria]

Summary

Wildcard patterns in ALLOWED_TOOLS (e.g., Bash(git *)) don't appear to work correctly. Even setting ALLOWED_TOOLS="*" still results in permission denials.

This was split from #143 which addressed the display bug for denied commands.

Evidence

User 1 (from #143)

ALLOWED_TOOLS="Write,Read,Edit,Bash(git *),Bash(npm *),Bash(pytest)"

Result: git commit commands blocked

User 2 (from #143)

ALLOWED_TOOLS="*"  # Allow EVERYTHING

Result: Still got permission denied after 1 API call

[2026-02-01 11:56:33] [SUCCESS] 🏁 Graceful exit triggered: permission_denied

Current Implementation

In ralph_loop.sh lines 950-960, tools are added to the command array:

if [[ -n "$CLAUDE_ALLOWED_TOOLS" ]]; then
    CLAUDE_CMD_ARGS+=("--allowedTools")
    local IFS=','
    read -ra tools_array <<< "$CLAUDE_ALLOWED_TOOLS"
    for tool in "${tools_array[@]}"; do
        tool=$(echo "$tool" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
        if [[ -n "$tool" ]]; then
            CLAUDE_CMD_ARGS+=("$tool")
        fi
    done
fi

This looks correct - tools are properly split and added.

Investigation Needed

1. Verify --allowedTools flag is reaching Claude CLI

   • Add debug logging to print the actual command being executed
   • Confirm the tools array is populated correctly

2. Test Claude CLI directly

   • Does claude --allowedTools "Bash(git *)" -p "run git status" work?
   • Does claude --allowedTools "*" -p "run npm install" work?
   • Test both interactive and non-interactive modes

3. Check Claude CLI documentation

   • Does Claude CLI support * as "allow all"?
   • What's the correct wildcard syntax for Bash commands?
   • Is there a difference between Bash(git *) vs Bash(git:*)?

4. Mode-specific behavior

   • Does the -p flag (non-interactive) have different permission handling?
   • Does --continue affect permissions?

Possible Causes

1. Claude CLI doesn't support * as "allow all tools"
2. Claude CLI doesn't support space-based wildcards in non-interactive mode
3. The --allowedTools flag isn't being passed in all code paths
4. Shell escaping issues when building the command

Related

• Permission denied error doesn't show which commands were blocked + Bash(git *) pattern not working #143 - Original issue (display bug fixed, wildcard issue moved here)
• No Approval Request, silent fail #101 - Permission denial detection feature
• lib/response_analyzer.sh - Permission denial extraction
• ralph_loop.sh - build_claude_command() function

[traycerai]

Plan

Observations

The issue involves wildcard patterns in ALLOWED_TOOLS not working correctly, even when set to "*". The current implementation in file:ralph_loop.sh (lines 952-964) correctly splits comma-separated tools and passes each as a separate argument to --allowedTools. However, there are several potential root causes: (1) Claude CLI may not support "*" as "allow all", (2) wildcard patterns may require specific syntax, (3) the flag may not be passed in all execution paths, or (4) there may be conflicts with permission modes.

The investigation revealed that:

• build_claude_command() correctly constructs the command array with --allowedTools flags
• ralph_import.sh uses array expansion "${CLAUDE_ALLOWED_TOOLS[@]}" for proper quoting
• Permission denials are detected via response_analyzer.sh which extracts permission_denials array from Claude CLI output
• Legacy CLI fallback (line 1173) does NOT pass --allowedTools, relying on interactive prompts
• Live streaming mode (line 1100) uses LIVE_CMD_ARGS which may not include tool permissions

Approach

The investigation will follow a systematic debugging approach: first, add comprehensive logging to verify the exact command being executed and confirm --allowedTools reaches Claude CLI; second, test Claude CLI directly with various wildcard patterns to isolate whether the issue is in Ralph's implementation or Claude CLI itself; third, verify the correct wildcard syntax and whether Claude CLI supports "*" as "allow all"; fourth, ensure --allowedTools is passed consistently across all execution modes (live streaming, background, modern vs legacy CLI); and fifth, identify whether the issue is related to how wildcards are escaped or interpreted by the Claude CLI parser. This approach prioritizes verification over speculation and will provide concrete evidence for the root cause.

Implementation Steps

1. Add Debug Logging for Command Verification

File: file:ralph_loop.sh

In the build_claude_command() function (after line 982), add debug logging to print the exact command array being constructed:

• After building CLAUDE_CMD_ARGS, add a debug log that prints the full command array
• Use log_status "DEBUG" to show each element of the array
• Make this conditional on VERBOSE_PROGRESS flag
• Log format: "Claude CLI command array (${#CLAUDE_CMD_ARGS[@]} elements):"
• Print each array element with index for visibility
• Include tool count and specific tool names in debug output

In the execute_claude_code() function (around lines 1100 and 1158), add logging before executing:

• For live mode (line 1100), log the LIVE_CMD_ARGS array before pipeline execution
• For background mode (line 1158), log the CLAUDE_CMD_ARGS array before background execution
• Include the exact command that will be executed
• Log whether --allowedTools flag is present in the array
• Log the raw CLAUDE_ALLOWED_TOOLS value before splitting to detect escaping issues

2. Create Test Script for Direct Claude CLI Testing

New file: file:tests/manual/test_allowed_tools.sh

Create a manual test script to verify Claude CLI behavior directly:

• Test 1: claude --allowedTools "Write" --allowedTools "Read" -p "list files" - verify multiple tools work
• Test 2: claude --allowedTools "*" -p "run git status" - test if "*" is supported
• Test 3: claude --allowedTools "Bash(git *)" -p "run git commit" - test wildcard syntax with space
• Test 4: claude --allowedTools "Bash(git*)" -p "run git status" - test wildcard without space
• Test 5: claude --allowedTools "Bash(git:*)" -p "run git status" - test colon-based wildcard syntax
• Test 6: Compare with --dangerously-skip-permissions behavior
• Test 7: Test with -p flag vs stdin piping to check mode-specific behavior
• Each test should capture output and check for permission denials
• Document expected vs actual behavior
• Include Claude CLI version check to ensure compatibility

3. Verify Wildcard Syntax Documentation

File: file:CLAUDE.md

Update the documentation section on ALLOWED_TOOLS to clarify:

• Document that "*" as a standalone value may NOT work as "allow all"
• Clarify that wildcards work WITHIN tool patterns: Bash(git *), not as "*"
• Add note that --dangerously-skip-permissions is the only way to truly allow all
• Include examples of correct wildcard syntax from Claude CLI docs
• Document the difference between space-based (Bash(git *)) and colon-based (Bash(git:*)) wildcard syntax
• Add troubleshooting section for permission denials
• Include note about Claude CLI version requirements for wildcard support

4. Investigate Alternative "Allow All" Approaches

File: file:ralph_loop.sh

In the build_claude_command() function, add logic to handle special cases:

• If CLAUDE_ALLOWED_TOOLS equals "*", log a warning that this may not work as "allow all"
• Suggest using --dangerously-skip-permissions instead (with appropriate warnings)
• Consider adding a new config option: CLAUDE_SKIP_PERMISSIONS=false
• When enabled, use --dangerously-skip-permissions instead of --allowedTools
• Document the security implications clearly
• Add validation to prevent both --allowedTools and --dangerously-skip-permissions from being used simultaneously
• Log which permission mode is being used (allowedTools vs skip-permissions)

5. Verify Flag Passing in All Execution Paths

File: file:ralph_loop.sh

Audit all code paths where Claude CLI is executed:

• Modern CLI path (line 1158): Verify CLAUDE_CMD_ARGS includes --allowedTools before execution
• Legacy CLI path (line 1173): This path does NOT use --allowedTools - add warning and log
• Live streaming path (line 1100): Verify LIVE_CMD_ARGS preserves --allowedTools from build_claude_command()
• Ensure the flag is not being stripped or modified during array manipulation
• Check if LIVE_CMD_ARGS is properly initialized with CLAUDE_CMD_ARGS values

In the legacy CLI fallback (lines 1169-1180):

• Add a warning log: "Legacy mode does not support --allowedTools, permissions will be interactive"
• Log the fallback reason to help diagnose why modern mode failed
• Consider forcing modern CLI mode when CLAUDE_ALLOWED_TOOLS is set to non-default values
• Prevent fallback to legacy mode if tool permissions are critical
• Add check to ensure Claude CLI version supports --allowedTools before using modern mode

6. Add Validation for Tool Patterns

File: file:ralph_loop.sh

Enhance the validate_allowed_tools() function (lines 537-581):

• Add specific validation for "*" and warn it may not work as "allow all"
• Validate wildcard syntax: Bash(command *) format
• Check for common mistakes: Bash(git*) (missing space) vs Bash(git *)
• Provide helpful error messages with correct syntax examples
• Add validation that wildcards are inside parentheses, not standalone
• Validate that tool names don't have leading/trailing spaces after comma splitting
• Check for unmatched parentheses in tool patterns
• Warn if using colon-based syntax (Bash(git:*)) vs space-based (Bash(git *))

7. Test with Different Claude CLI Versions

File: file:tests/integration/test_allowed_tools.bats

Create integration tests for --allowedTools behavior:

• Test that --allowedTools flag is included in command array
• Test that wildcards are preserved correctly (no shell expansion)
• Test that comma-separated tools are split into separate arguments
• Mock Claude CLI to verify exact arguments received
• Test both modern and legacy CLI paths
• Test that "*" is handled with appropriate warning
• Test that tool patterns with spaces are preserved
• Test that tool patterns without spaces generate warnings
• Verify that LIVE_CMD_ARGS includes --allowedTools flags

8. Add Troubleshooting Guide

File: file:docs/troubleshooting/allowed-tools.md

Create a comprehensive troubleshooting guide:

• Symptom: Permission denied despite setting ALLOWED_TOOLS
• Diagnosis steps:
  1. Enable verbose mode: ralph --verbose
  2. Check logs for actual command executed
  3. Test Claude CLI directly with same flags
  4. Verify Claude CLI version >= 2.0.76
  5. Check if using legacy CLI fallback (indicates modern CLI failed)
  6. Verify wildcard syntax matches Claude CLI expectations
• Common issues:
  • "*" doesn't mean "allow all" - use specific tools or --dangerously-skip-permissions
  • Wildcard syntax must be Bash(git *) not Bash(git*) (space is required)
  • Legacy CLI mode doesn't support --allowedTools (falls back to interactive prompts)
  • Claude CLI version < 2.0.76 may not support --allowedTools flag
  • Colon-based syntax (Bash(git:*)) may not work in all Claude CLI versions
• Solutions: Provide working examples for common scenarios
• Debug output: Explain how to interpret verbose logs to see exact command being executed

9. Update Template Configuration

File: file:lib/enable_core.sh and file:setup.sh

Update the template with better examples and warnings:

• Update default ALLOWED_TOOLS value with inline comments explaining syntax
• Add comments explaining wildcard syntax (space-based: Bash(git *))
• Add warning that "*" is NOT supported as "allow all"
• Provide examples for common development scenarios (git, npm, pytest)
• Add reference to troubleshooting documentation
• Include note about Claude CLI version requirements
• Add example showing how to use --dangerously-skip-permissions if needed

10. Consider Adding Permission Mode Support

File: file:ralph_loop.sh

Add support for Claude CLI's --permission-mode flag:

• New config variable: CLAUDE_PERMISSION_MODE (values: interactive, bypassPermissions)
• When set to bypassPermissions, use --permission-mode bypassPermissions instead of --allowedTools
• Add validation that --allowedTools and --permission-mode bypassPermissions are mutually exclusive
• Document the security implications of each mode
• Add to build_claude_command() to conditionally add --permission-mode flag
• Update .ralphrc template to document this option
• Add validation in validate_allowed_tools() to check for conflicting settings

Investigation Sequence

1. Enable verbose logging to see exact commands being executed
2. Test Claude CLI directly with various --allowedTools patterns to isolate Ralph vs Claude CLI issues
3. Verify wildcard syntax from Claude CLI documentation and test both space-based and colon-based patterns
4. Check all execution paths to ensure flags are passed consistently (modern, legacy, live streaming)
5. Validate tool patterns to catch common mistakes (missing spaces, unmatched parentheses)
6. Document findings in troubleshooting guide with specific examples
7. Implement fixes based on root cause findings (Ralph bug, Claude CLI limitation, or documentation gap)
8. Add tests to prevent regression and verify wildcard patterns work correctly

Expected Outcomes

After implementing these steps, you will have:

1. Visibility: Debug logs showing exact command being executed, including array elements and tool count
2. Verification: Direct Claude CLI tests isolating whether the issue is in Ralph or Claude CLI itself
3. Documentation: Clear guidance on correct wildcard syntax with examples of working and non-working patterns
4. Validation: Enhanced error checking for common mistakes (missing spaces, unmatched parentheses, "*" usage)
5. Alternatives: Support for --permission-mode or --dangerously-skip-permissions as fallback options
6. Troubleshooting: Comprehensive guide for users experiencing this issue with diagnostic steps
7. Tests: Integration tests verifying wildcard patterns work correctly across all execution modes

The investigation will determine whether this is:

• A Ralph implementation bug (incorrect flag passing or array construction)
• A Claude CLI limitation (wildcards not supported as expected, or "*" not meaning "allow all")
• A documentation gap (incorrect usage examples or missing syntax clarification)
• A version compatibility issue (older Claude CLI versions not supporting wildcards)
• A shell escaping issue (wildcards being expanded or modified during command construction)

Import In IDE

🤖 Prompt for AI Agents

## Observations

The issue involves wildcard patterns in `ALLOWED_TOOLS` not working correctly, even when set to `"*"`. The current implementation in `file:ralph_loop.sh` (lines 952-964) correctly splits comma-separated tools and passes each as a separate argument to `--allowedTools`. However, there are several potential root causes: (1) Claude CLI may not support `"*"` as "allow all", (2) wildcard patterns may require specific syntax, (3) the flag may not be passed in all execution paths, or (4) there may be conflicts with permission modes.

The investigation revealed that:
- `build_claude_command()` correctly constructs the command array with `--allowedTools` flags
- `ralph_import.sh` uses array expansion `"${CLAUDE_ALLOWED_TOOLS[@]}"` for proper quoting
- Permission denials are detected via `response_analyzer.sh` which extracts `permission_denials` array from Claude CLI output
- Legacy CLI fallback (line 1173) does NOT pass `--allowedTools`, relying on interactive prompts
- Live streaming mode (line 1100) uses `LIVE_CMD_ARGS` which may not include tool permissions

## Approach

The investigation will follow a systematic debugging approach: first, add comprehensive logging to verify the exact command being executed and confirm `--allowedTools` reaches Claude CLI; second, test Claude CLI directly with various wildcard patterns to isolate whether the issue is in Ralph's implementation or Claude CLI itself; third, verify the correct wildcard syntax and whether Claude CLI supports `"*"` as "allow all"; fourth, ensure `--allowedTools` is passed consistently across all execution modes (live streaming, background, modern vs legacy CLI); and fifth, identify whether the issue is related to how wildcards are escaped or interpreted by the Claude CLI parser. This approach prioritizes verification over speculation and will provide concrete evidence for the root cause.

## Implementation Steps

### 1. Add Debug Logging for Command Verification

**File: `file:ralph_loop.sh`**

In the `build_claude_command()` function (after line 982), add debug logging to print the exact command array being constructed:

- After building `CLAUDE_CMD_ARGS`, add a debug log that prints the full command array
- Use `log_status "DEBUG"` to show each element of the array
- Make this conditional on `VERBOSE_PROGRESS` flag
- Log format: `"Claude CLI command array (${#CLAUDE_CMD_ARGS[@]} elements):"`
- Print each array element with index for visibility
- Include tool count and specific tool names in debug output

In the `execute_claude_code()` function (around lines 1100 and 1158), add logging before executing:

- For live mode (line 1100), log the `LIVE_CMD_ARGS` array before pipeline execution
- For background mode (line 1158), log the `CLAUDE_CMD_ARGS` array before background execution
- Include the exact command that will be executed
- Log whether `--allowedTools` flag is present in the array
- Log the raw `CLAUDE_ALLOWED_TOOLS` value before splitting to detect escaping issues

### 2. Create Test Script for Direct Claude CLI Testing

**New file: `file:tests/manual/test_allowed_tools.sh`**

Create a manual test script to verify Claude CLI behavior directly:

- Test 1: `claude --allowedTools "Write" --allowedTools "Read" -p "list files"` - verify multiple tools work
- Test 2: `claude --allowedTools "*" -p "run git status"` - test if `"*"` is supported
- Test 3: `claude --allowedTools "Bash(git *)" -p "run git commit"` - test wildcard syntax with space
- Test 4: `claude --allowedTools "Bash(git*)" -p "run git status"` - test wildcard without space
- Test 5: `claude --allowedTools "Bash(git:*)" -p "run git status"` - test colon-based wildcard syntax
- Test 6: Compare with `--dangerously-skip-permissions` behavior
- Test 7: Test with `-p` flag vs stdin piping to check mode-specific behavior
- Each test should capture output and check for permission denials
- Document expected vs actual behavior
- Include Claude CLI version check to ensure compatibility

### 3. Verify Wildcard Syntax Documentation

**File: `file:CLAUDE.md`**

Update the documentation section on `ALLOWED_TOOLS` to clarify:

- Document that `"*"` as a standalone value may NOT work as "allow all"
- Clarify that wildcards work WITHIN tool patterns: `Bash(git *)`, not as `"*"`
- Add note that `--dangerously-skip-permissions` is the only way to truly allow all
- Include examples of correct wildcard syntax from Claude CLI docs
- Document the difference between space-based (`Bash(git *)`) and colon-based (`Bash(git:*)`) wildcard syntax
- Add troubleshooting section for permission denials
- Include note about Claude CLI version requirements for wildcard support

### 4. Investigate Alternative "Allow All" Approaches

**File: `file:ralph_loop.sh`**

In the `build_claude_command()` function, add logic to handle special cases:

- If `CLAUDE_ALLOWED_TOOLS` equals `"*"`, log a warning that this may not work as "allow all"
- Suggest using `--dangerously-skip-permissions` instead (with appropriate warnings)
- Consider adding a new config option: `CLAUDE_SKIP_PERMISSIONS=false`
- When enabled, use `--dangerously-skip-permissions` instead of `--allowedTools`
- Document the security implications clearly
- Add validation to prevent both `--allowedTools` and `--dangerously-skip-permissions` from being used simultaneously
- Log which permission mode is being used (allowedTools vs skip-permissions)

### 5. Verify Flag Passing in All Execution Paths

**File: `file:ralph_loop.sh`**

Audit all code paths where Claude CLI is executed:

- **Modern CLI path** (line 1158): Verify `CLAUDE_CMD_ARGS` includes `--allowedTools` before execution
- **Legacy CLI path** (line 1173): This path does NOT use `--allowedTools` - add warning and log
- **Live streaming path** (line 1100): Verify `LIVE_CMD_ARGS` preserves `--allowedTools` from `build_claude_command()`
- Ensure the flag is not being stripped or modified during array manipulation
- Check if `LIVE_CMD_ARGS` is properly initialized with `CLAUDE_CMD_ARGS` values

In the legacy CLI fallback (lines 1169-1180):

- Add a warning log: "Legacy mode does not support --allowedTools, permissions will be interactive"
- Log the fallback reason to help diagnose why modern mode failed
- Consider forcing modern CLI mode when `CLAUDE_ALLOWED_TOOLS` is set to non-default values
- Prevent fallback to legacy mode if tool permissions are critical
- Add check to ensure Claude CLI version supports `--allowedTools` before using modern mode

### 6. Add Validation for Tool Patterns

**File: `file:ralph_loop.sh`**

Enhance the `validate_allowed_tools()` function (lines 537-581):

- Add specific validation for `"*"` and warn it may not work as "allow all"
- Validate wildcard syntax: `Bash(command *)` format
- Check for common mistakes: `Bash(git*)` (missing space) vs `Bash(git *)`
- Provide helpful error messages with correct syntax examples
- Add validation that wildcards are inside parentheses, not standalone
- Validate that tool names don't have leading/trailing spaces after comma splitting
- Check for unmatched parentheses in tool patterns
- Warn if using colon-based syntax (`Bash(git:*)`) vs space-based (`Bash(git *)`)

### 7. Test with Different Claude CLI Versions

**File: `file:tests/integration/test_allowed_tools.bats`**

Create integration tests for `--allowedTools` behavior:

- Test that `--allowedTools` flag is included in command array
- Test that wildcards are preserved correctly (no shell expansion)
- Test that comma-separated tools are split into separate arguments
- Mock Claude CLI to verify exact arguments received
- Test both modern and legacy CLI paths
- Test that `"*"` is handled with appropriate warning
- Test that tool patterns with spaces are preserved
- Test that tool patterns without spaces generate warnings
- Verify that `LIVE_CMD_ARGS` includes `--allowedTools` flags

### 8. Add Troubleshooting Guide

**File: `file:docs/troubleshooting/allowed-tools.md`**

Create a comprehensive troubleshooting guide:

- **Symptom**: Permission denied despite setting `ALLOWED_TOOLS`
- **Diagnosis steps**: 
  1. Enable verbose mode: `ralph --verbose`
  2. Check logs for actual command executed
  3. Test Claude CLI directly with same flags
  4. Verify Claude CLI version >= 2.0.76
  5. Check if using legacy CLI fallback (indicates modern CLI failed)
  6. Verify wildcard syntax matches Claude CLI expectations
- **Common issues**:
  - `"*"` doesn't mean "allow all" - use specific tools or `--dangerously-skip-permissions`
  - Wildcard syntax must be `Bash(git *)` not `Bash(git*)` (space is required)
  - Legacy CLI mode doesn't support `--allowedTools` (falls back to interactive prompts)
  - Claude CLI version < 2.0.76 may not support `--allowedTools` flag
  - Colon-based syntax (`Bash(git:*)`) may not work in all Claude CLI versions
- **Solutions**: Provide working examples for common scenarios
- **Debug output**: Explain how to interpret verbose logs to see exact command being executed

### 9. Update Template Configuration

**File: `file:lib/enable_core.sh` and `file:setup.sh`**

Update the template with better examples and warnings:

- Update default `ALLOWED_TOOLS` value with inline comments explaining syntax
- Add comments explaining wildcard syntax (space-based: `Bash(git *)`)
- Add warning that `"*"` is NOT supported as "allow all"
- Provide examples for common development scenarios (git, npm, pytest)
- Add reference to troubleshooting documentation
- Include note about Claude CLI version requirements
- Add example showing how to use `--dangerously-skip-permissions` if needed

### 10. Consider Adding Permission Mode Support

**File: `file:ralph_loop.sh`**

Add support for Claude CLI's `--permission-mode` flag:

- New config variable: `CLAUDE_PERMISSION_MODE` (values: `interactive`, `bypassPermissions`)
- When set to `bypassPermissions`, use `--permission-mode bypassPermissions` instead of `--allowedTools`
- Add validation that `--allowedTools` and `--permission-mode bypassPermissions` are mutually exclusive
- Document the security implications of each mode
- Add to `build_claude_command()` to conditionally add `--permission-mode` flag
- Update `.ralphrc` template to document this option
- Add validation in `validate_allowed_tools()` to check for conflicting settings

## Investigation Sequence

1. **Enable verbose logging** to see exact commands being executed
2. **Test Claude CLI directly** with various `--allowedTools` patterns to isolate Ralph vs Claude CLI issues
3. **Verify wildcard syntax** from Claude CLI documentation and test both space-based and colon-based patterns
4. **Check all execution paths** to ensure flags are passed consistently (modern, legacy, live streaming)
5. **Validate tool patterns** to catch common mistakes (missing spaces, unmatched parentheses)
6. **Document findings** in troubleshooting guide with specific examples
7. **Implement fixes** based on root cause findings (Ralph bug, Claude CLI limitation, or documentation gap)
8. **Add tests** to prevent regression and verify wildcard patterns work correctly

## Expected Outcomes

After implementing these steps, you will have:

1. **Visibility**: Debug logs showing exact command being executed, including array elements and tool count
2. **Verification**: Direct Claude CLI tests isolating whether the issue is in Ralph or Claude CLI itself
3. **Documentation**: Clear guidance on correct wildcard syntax with examples of working and non-working patterns
4. **Validation**: Enhanced error checking for common mistakes (missing spaces, unmatched parentheses, `"*"` usage)
5. **Alternatives**: Support for `--permission-mode` or `--dangerously-skip-permissions` as fallback options
6. **Troubleshooting**: Comprehensive guide for users experiencing this issue with diagnostic steps
7. **Tests**: Integration tests verifying wildcard patterns work correctly across all execution modes

The investigation will determine whether this is:
- A Ralph implementation bug (incorrect flag passing or array construction)
- A Claude CLI limitation (wildcards not supported as expected, or `"*"` not meaning "allow all")
- A documentation gap (incorrect usage examples or missing syntax clarification)
- A version compatibility issue (older Claude CLI versions not supporting wildcards)
- A shell escaping issue (wildcards being expanded or modified during command construction)

---

Execution Information

Branch: main
Commit: 627ad7d

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#137 - fix(setup): create .ralphrc with consistent tool permissions [merged]
#142 - feat(exit): detect permission denials and halt loop (Issue #101) [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[traycerai]

I have updated the Implementation Plan to reflect the recent changes in the ticket.

Previous Plan

Observations

The issue involves wildcard patterns in ALLOWED_TOOLS not working correctly, even when set to "*". The current implementation in file:ralph_loop.sh (lines 952-964) correctly splits comma-separated tools and passes each as a separate argument to --allowedTools. However, there are several potential root causes: (1) Claude CLI may not support "*" as "allow all", (2) wildcard patterns may require specific syntax, (3) the flag may not be passed in all execution paths, or (4) there may be conflicts with permission modes.

Approach

The investigation will follow a systematic debugging approach: first, add comprehensive logging to verify the exact command being executed; second, test Claude CLI directly to isolate whether the issue is in Ralph's implementation or Claude CLI itself; third, verify the correct wildcard syntax from Claude CLI documentation; and fourth, ensure --allowedTools is passed consistently across all execution modes (live streaming, background, modern vs legacy CLI). This approach prioritizes verification over speculation and will provide concrete evidence for the root cause.

Implementation Steps

1. Add Debug Logging for Command Verification

File: file:ralph_loop.sh

In the build_claude_command() function (after line 982), add debug logging to print the exact command array being constructed:

• After building CLAUDE_CMD_ARGS, add a debug log that prints the full command array
• Use log_status "DEBUG" to show each element of the array
• Make this conditional on VERBOSE_PROGRESS or a new DEBUG_MODE flag
• Log format: "Claude CLI command: ${CLAUDE_CMD_ARGS[@]}"

In the execute_claude_code() function (around lines 1100 and 1158), add logging before executing:

• For live mode (line 1100), log the LIVE_CMD_ARGS array
• For background mode (line 1158), log the CLAUDE_CMD_ARGS array
• Include the exact command that will be executed

2. Create Test Script for Direct Claude CLI Testing

New file: file:tests/manual/test_allowed_tools.sh

Create a manual test script to verify Claude CLI behavior directly:

• Test 1: claude --allowedTools "Write" --allowedTools "Read" -p "list files"
• Test 2: claude --allowedTools "*" -p "run git status"
• Test 3: claude --allowedTools "Bash(git *)" -p "run git commit"
• Test 4: Compare with --dangerously-skip-permissions behavior
• Each test should capture output and check for permission denials
• Document expected vs actual behavior

3. Verify Wildcard Syntax Documentation

File: file:CLAUDE.md

Update the documentation section on ALLOWED_TOOLS (around line 396-403) to clarify:

• Document that "*" as a standalone value may NOT work as "allow all"
• Clarify that wildcards work WITHIN tool patterns: Bash(git *), not as "*"
• Add note that --dangerously-skip-permissions is the only way to truly allow all
• Include examples of correct wildcard syntax from Claude CLI docs
• Add troubleshooting section for permission denials

4. Investigate Alternative "Allow All" Approaches

File: file:ralph_loop.sh

In the build_claude_command() function, add logic to handle special cases:

• If CLAUDE_ALLOWED_TOOLS equals "*", log a warning that this may not work
• Suggest using --dangerously-skip-permissions instead (with appropriate warnings)
• Consider adding a new config option: CLAUDE_SKIP_PERMISSIONS=false
• When enabled, use --dangerously-skip-permissions instead of --allowedTools
• Document the security implications clearly

5. Verify Flag Passing in All Execution Paths

File: file:ralph_loop.sh

Audit all code paths where Claude CLI is executed:

• Modern CLI path (line 1158): Verify CLAUDE_CMD_ARGS includes --allowedTools
• Legacy CLI path (line 1173): This path does NOT use --allowedTools - add warning
• Live streaming path (line 1100): Verify LIVE_CMD_ARGS preserves --allowedTools
• Ensure the flag is not being stripped or modified during array manipulation

In the legacy CLI fallback (lines 1169-1180):

• Add a warning log: "Legacy mode does not support --allowedTools, permissions will be interactive"
• Consider forcing modern CLI mode when CLAUDE_ALLOWED_TOOLS is set
• Prevent fallback to legacy mode if tool permissions are critical

6. Add Validation for Tool Patterns

File: file:ralph_loop.sh

Enhance the validate_allowed_tools() function (lines 537-581):

• Add specific validation for "*" and warn it may not work
• Validate wildcard syntax: Bash(command *) format
• Check for common mistakes: Bash(git*) (missing space) vs Bash(git *)
• Provide helpful error messages with correct syntax examples
• Add validation that wildcards are inside parentheses, not standalone

7. Test with Different Claude CLI Versions

File: file:tests/integration/test_allowed_tools.bats

Create integration tests for --allowedTools behavior:

• Test that --allowedTools flag is included in command array
• Test that wildcards are preserved correctly (no shell expansion)
• Test that comma-separated tools are split into separate arguments
• Mock Claude CLI to verify exact arguments received
• Test both modern and legacy CLI paths

8. Add Troubleshooting Guide

File: file:docs/troubleshooting/allowed-tools.md

Create a comprehensive troubleshooting guide:

• Symptom: Permission denied despite setting ALLOWED_TOOLS
• Diagnosis steps:
  1. Enable verbose mode: ralph --verbose
  2. Check logs for actual command executed
  3. Test Claude CLI directly with same flags
  4. Verify Claude CLI version >= 2.0.76
• Common issues:
  • "*" doesn't mean "allow all" - use specific tools or --dangerously-skip-permissions
  • Wildcard syntax must be Bash(git *) not Bash(git*)
  • Legacy CLI mode doesn't support --allowedTools
• Solutions: Provide working examples for common scenarios

9. Update Template Configuration

File: file:templates/ralphrc.template

Update the template with better examples and warnings:

• Change line 39 to include more comprehensive examples
• Add comments explaining wildcard syntax
• Add warning that "*" is NOT supported as "allow all"
• Provide examples for common development scenarios
• Add reference to troubleshooting documentation

10. Consider Adding Permission Mode Support

File: file:ralph_loop.sh

Add support for Claude CLI's --permission-mode flag:

• New config variable: CLAUDE_PERMISSION_MODE (values: interactive, bypassPermissions)
• When set to bypassPermissions, use --permission-mode bypassPermissions instead of --allowedTools
• Add validation that --allowedTools and --permission-mode bypassPermissions are mutually exclusive
• Document the security implications of each mode

Investigation Sequence Diagram

sequenceDiagram
    participant User
    participant Ralph
    participant ClaudeCLI
    participant Logs

    User->>Ralph: Set ALLOWED_TOOLS="*"
    Ralph->>Ralph: build_claude_command()
    Ralph->>Logs: Log command array
    Ralph->>ClaudeCLI: Execute with --allowedTools
    ClaudeCLI-->>Ralph: Permission denied
    Ralph->>Ralph: parse_json_response()
    Ralph->>Ralph: Extract permission_denials
    Ralph->>Logs: Log denied commands
    Ralph->>User: Display error + guidance
    
    Note over User,ClaudeCLI: Investigation Path
    User->>ClaudeCLI: Test directly: claude --allowedTools "*"
    ClaudeCLI-->>User: Verify if "*" works
    User->>ClaudeCLI: Test: claude --allowedTools "Bash(git *)"
    ClaudeCLI-->>User: Verify wildcard syntax
    User->>Ralph: Update ALLOWED_TOOLS with correct syntax
    Ralph->>ClaudeCLI: Execute with corrected flags
    ClaudeCLI-->>Ralph: Success or specific error

Loading

Expected Outcomes

After implementing these steps, you will have:

1. Visibility: Debug logs showing exact command being executed
2. Verification: Direct Claude CLI tests isolating the issue
3. Documentation: Clear guidance on correct wildcard syntax
4. Validation: Enhanced error checking for common mistakes
5. Alternatives: Support for --permission-mode or --dangerously-skip-permissions
6. Troubleshooting: Comprehensive guide for users experiencing this issue

The investigation will determine whether this is:

• A Ralph implementation bug (incorrect flag passing)
• A Claude CLI limitation (wildcards not supported as expected)
• A documentation gap (incorrect usage examples)
• A version compatibility issue (older Claude CLI versions)

Import In IDE

🤖 Prompt for AI Agents

## Observations

The issue involves wildcard patterns in `ALLOWED_TOOLS` not working correctly, even when set to `"*"`. The current implementation in `file:ralph_loop.sh` (lines 952-964) correctly splits comma-separated tools and passes each as a separate argument to `--allowedTools`. However, there are several potential root causes: (1) Claude CLI may not support `"*"` as "allow all", (2) wildcard patterns may require specific syntax, (3) the flag may not be passed in all execution paths, or (4) there may be conflicts with permission modes.

## Approach

The investigation will follow a systematic debugging approach: first, add comprehensive logging to verify the exact command being executed; second, test Claude CLI directly to isolate whether the issue is in Ralph's implementation or Claude CLI itself; third, verify the correct wildcard syntax from Claude CLI documentation; and fourth, ensure `--allowedTools` is passed consistently across all execution modes (live streaming, background, modern vs legacy CLI). This approach prioritizes verification over speculation and will provide concrete evidence for the root cause.

## Implementation Steps

### 1. Add Debug Logging for Command Verification

**File: `file:ralph_loop.sh`**

In the `build_claude_command()` function (after line 982), add debug logging to print the exact command array being constructed:

- After building `CLAUDE_CMD_ARGS`, add a debug log that prints the full command array
- Use `log_status "DEBUG"` to show each element of the array
- Make this conditional on `VERBOSE_PROGRESS` or a new `DEBUG_MODE` flag
- Log format: `"Claude CLI command: ${CLAUDE_CMD_ARGS[@]}"`

In the `execute_claude_code()` function (around lines 1100 and 1158), add logging before executing:

- For live mode (line 1100), log the `LIVE_CMD_ARGS` array
- For background mode (line 1158), log the `CLAUDE_CMD_ARGS` array
- Include the exact command that will be executed

### 2. Create Test Script for Direct Claude CLI Testing

**New file: `file:tests/manual/test_allowed_tools.sh`**

Create a manual test script to verify Claude CLI behavior directly:

- Test 1: `claude --allowedTools "Write" --allowedTools "Read" -p "list files"`
- Test 2: `claude --allowedTools "*" -p "run git status"`
- Test 3: `claude --allowedTools "Bash(git *)" -p "run git commit"`
- Test 4: Compare with `--dangerously-skip-permissions` behavior
- Each test should capture output and check for permission denials
- Document expected vs actual behavior

### 3. Verify Wildcard Syntax Documentation

**File: `file:CLAUDE.md`**

Update the documentation section on `ALLOWED_TOOLS` (around line 396-403) to clarify:

- Document that `"*"` as a standalone value may NOT work as "allow all"
- Clarify that wildcards work WITHIN tool patterns: `Bash(git *)`, not as `"*"`
- Add note that `--dangerously-skip-permissions` is the only way to truly allow all
- Include examples of correct wildcard syntax from Claude CLI docs
- Add troubleshooting section for permission denials

### 4. Investigate Alternative "Allow All" Approaches

**File: `file:ralph_loop.sh`**

In the `build_claude_command()` function, add logic to handle special cases:

- If `CLAUDE_ALLOWED_TOOLS` equals `"*"`, log a warning that this may not work
- Suggest using `--dangerously-skip-permissions` instead (with appropriate warnings)
- Consider adding a new config option: `CLAUDE_SKIP_PERMISSIONS=false`
- When enabled, use `--dangerously-skip-permissions` instead of `--allowedTools`
- Document the security implications clearly

### 5. Verify Flag Passing in All Execution Paths

**File: `file:ralph_loop.sh`**

Audit all code paths where Claude CLI is executed:

- **Modern CLI path** (line 1158): Verify `CLAUDE_CMD_ARGS` includes `--allowedTools`
- **Legacy CLI path** (line 1173): This path does NOT use `--allowedTools` - add warning
- **Live streaming path** (line 1100): Verify `LIVE_CMD_ARGS` preserves `--allowedTools`
- Ensure the flag is not being stripped or modified during array manipulation

In the legacy CLI fallback (lines 1169-1180):

- Add a warning log: "Legacy mode does not support --allowedTools, permissions will be interactive"
- Consider forcing modern CLI mode when `CLAUDE_ALLOWED_TOOLS` is set
- Prevent fallback to legacy mode if tool permissions are critical

### 6. Add Validation for Tool Patterns

**File: `file:ralph_loop.sh`**

Enhance the `validate_allowed_tools()` function (lines 537-581):

- Add specific validation for `"*"` and warn it may not work
- Validate wildcard syntax: `Bash(command *)` format
- Check for common mistakes: `Bash(git*)` (missing space) vs `Bash(git *)`
- Provide helpful error messages with correct syntax examples
- Add validation that wildcards are inside parentheses, not standalone

### 7. Test with Different Claude CLI Versions

**File: `file:tests/integration/test_allowed_tools.bats`**

Create integration tests for `--allowedTools` behavior:

- Test that `--allowedTools` flag is included in command array
- Test that wildcards are preserved correctly (no shell expansion)
- Test that comma-separated tools are split into separate arguments
- Mock Claude CLI to verify exact arguments received
- Test both modern and legacy CLI paths

### 8. Add Troubleshooting Guide

**File: `file:docs/troubleshooting/allowed-tools.md`**

Create a comprehensive troubleshooting guide:

- **Symptom**: Permission denied despite setting `ALLOWED_TOOLS`
- **Diagnosis steps**: 
  1. Enable verbose mode: `ralph --verbose`
  2. Check logs for actual command executed
  3. Test Claude CLI directly with same flags
  4. Verify Claude CLI version >= 2.0.76
- **Common issues**:
  - `"*"` doesn't mean "allow all" - use specific tools or `--dangerously-skip-permissions`
  - Wildcard syntax must be `Bash(git *)` not `Bash(git*)`
  - Legacy CLI mode doesn't support `--allowedTools`
- **Solutions**: Provide working examples for common scenarios

### 9. Update Template Configuration

**File: `file:templates/ralphrc.template`**

Update the template with better examples and warnings:

- Change line 39 to include more comprehensive examples
- Add comments explaining wildcard syntax
- Add warning that `"*"` is NOT supported as "allow all"
- Provide examples for common development scenarios
- Add reference to troubleshooting documentation

### 10. Consider Adding Permission Mode Support

**File: `file:ralph_loop.sh`**

Add support for Claude CLI's `--permission-mode` flag:

- New config variable: `CLAUDE_PERMISSION_MODE` (values: `interactive`, `bypassPermissions`)
- When set to `bypassPermissions`, use `--permission-mode bypassPermissions` instead of `--allowedTools`
- Add validation that `--allowedTools` and `--permission-mode bypassPermissions` are mutually exclusive
- Document the security implications of each mode

## Investigation Sequence Diagram

```mermaid
sequenceDiagram
    participant User
    participant Ralph
    participant ClaudeCLI
    participant Logs

    User->>Ralph: Set ALLOWED_TOOLS="*"
    Ralph->>Ralph: build_claude_command()
    Ralph->>Logs: Log command array
    Ralph->>ClaudeCLI: Execute with --allowedTools
    ClaudeCLI-->>Ralph: Permission denied
    Ralph->>Ralph: parse_json_response()
    Ralph->>Ralph: Extract permission_denials
    Ralph->>Logs: Log denied commands
    Ralph->>User: Display error + guidance
    
    Note over User,ClaudeCLI: Investigation Path
    User->>ClaudeCLI: Test directly: claude --allowedTools "*"
    ClaudeCLI-->>User: Verify if "*" works
    User->>ClaudeCLI: Test: claude --allowedTools "Bash(git *)"
    ClaudeCLI-->>User: Verify wildcard syntax
    User->>Ralph: Update ALLOWED_TOOLS with correct syntax
    Ralph->>ClaudeCLI: Execute with corrected flags
    ClaudeCLI-->>Ralph: Success or specific error
```

## Expected Outcomes

After implementing these steps, you will have:

1. **Visibility**: Debug logs showing exact command being executed
2. **Verification**: Direct Claude CLI tests isolating the issue
3. **Documentation**: Clear guidance on correct wildcard syntax
4. **Validation**: Enhanced error checking for common mistakes
5. **Alternatives**: Support for `--permission-mode` or `--dangerously-skip-permissions`
6. **Troubleshooting**: Comprehensive guide for users experiencing this issue

The investigation will determine whether this is:
- A Ralph implementation bug (incorrect flag passing)
- A Claude CLI limitation (wildcards not supported as expected)
- A documentation gap (incorrect usage examples)
- A version compatibility issue (older Claude CLI versions)

---

Execution Information

Branch: main
Commit: 627ad7d

New Plan

Observations

The issue involves wildcard patterns in ALLOWED_TOOLS not working correctly, even when set to "*". The current implementation in file:ralph_loop.sh (lines 952-964) correctly splits comma-separated tools and passes each as a separate argument to --allowedTools. However, there are several potential root causes: (1) Claude CLI may not support "*" as "allow all", (2) wildcard patterns may require specific syntax, (3) the flag may not be passed in all execution paths, or (4) there may be conflicts with permission modes.

The investigation revealed that:

• build_claude_command() correctly constructs the command array with --allowedTools flags
• ralph_import.sh uses array expansion "${CLAUDE_ALLOWED_TOOLS[@]}" for proper quoting
• Permission denials are detected via response_analyzer.sh which extracts permission_denials array from Claude CLI output
• Legacy CLI fallback (line 1173) does NOT pass --allowedTools, relying on interactive prompts
• Live streaming mode (line 1100) uses LIVE_CMD_ARGS which may not include tool permissions

Approach

The investigation will follow a systematic debugging approach: first, add comprehensive logging to verify the exact command being executed and confirm --allowedTools reaches Claude CLI; second, test Claude CLI directly with various wildcard patterns to isolate whether the issue is in Ralph's implementation or Claude CLI itself; third, verify the correct wildcard syntax and whether Claude CLI supports "*" as "allow all"; fourth, ensure --allowedTools is passed consistently across all execution modes (live streaming, background, modern vs legacy CLI); and fifth, identify whether the issue is related to how wildcards are escaped or interpreted by the Claude CLI parser. This approach prioritizes verification over speculation and will provide concrete evidence for the root cause.

Implementation Steps

1. Add Debug Logging for Command Verification

File: file:ralph_loop.sh

In the build_claude_command() function (after line 982), add debug logging to print the exact command array being constructed:

• After building CLAUDE_CMD_ARGS, add a debug log that prints the full command array
• Use log_status "DEBUG" to show each element of the array
• Make this conditional on VERBOSE_PROGRESS flag
• Log format: "Claude CLI command array (${#CLAUDE_CMD_ARGS[@]} elements):"
• Print each array element with index for visibility
• Include tool count and specific tool names in debug output

In the execute_claude_code() function (around lines 1100 and 1158), add logging before executing:

• For live mode (line 1100), log the LIVE_CMD_ARGS array before pipeline execution
• For background mode (line 1158), log the CLAUDE_CMD_ARGS array before background execution
• Include the exact command that will be executed
• Log whether --allowedTools flag is present in the array
• Log the raw CLAUDE_ALLOWED_TOOLS value before splitting to detect escaping issues

2. Create Test Script for Direct Claude CLI Testing

New file: file:tests/manual/test_allowed_tools.sh

Create a manual test script to verify Claude CLI behavior directly:

• Test 1: claude --allowedTools "Write" --allowedTools "Read" -p "list files" - verify multiple tools work
• Test 2: claude --allowedTools "*" -p "run git status" - test if "*" is supported
• Test 3: claude --allowedTools "Bash(git *)" -p "run git commit" - test wildcard syntax with space
• Test 4: claude --allowedTools "Bash(git*)" -p "run git status" - test wildcard without space
• Test 5: claude --allowedTools "Bash(git:*)" -p "run git status" - test colon-based wildcard syntax
• Test 6: Compare with --dangerously-skip-permissions behavior
• Test 7: Test with -p flag vs stdin piping to check mode-specific behavior
• Each test should capture output and check for permission denials
• Document expected vs actual behavior
• Include Claude CLI version check to ensure compatibility

3. Verify Wildcard Syntax Documentation

File: file:CLAUDE.md

Update the documentation section on ALLOWED_TOOLS to clarify:

• Document that "*" as a standalone value may NOT work as "allow all"
• Clarify that wildcards work WITHIN tool patterns: Bash(git *), not as "*"
• Add note that --dangerously-skip-permissions is the only way to truly allow all
• Include examples of correct wildcard syntax from Claude CLI docs
• Document the difference between space-based (Bash(git *)) and colon-based (Bash(git:*)) wildcard syntax
• Add troubleshooting section for permission denials
• Include note about Claude CLI version requirements for wildcard support

4. Investigate Alternative "Allow All" Approaches

File: file:ralph_loop.sh

In the build_claude_command() function, add logic to handle special cases:

• If CLAUDE_ALLOWED_TOOLS equals "*", log a warning that this may not work as "allow all"
• Suggest using --dangerously-skip-permissions instead (with appropriate warnings)
• Consider adding a new config option: CLAUDE_SKIP_PERMISSIONS=false
• When enabled, use --dangerously-skip-permissions instead of --allowedTools
• Document the security implications clearly
• Add validation to prevent both --allowedTools and --dangerously-skip-permissions from being used simultaneously
• Log which permission mode is being used (allowedTools vs skip-permissions)

5. Verify Flag Passing in All Execution Paths

File: file:ralph_loop.sh

Audit all code paths where Claude CLI is executed:

• Modern CLI path (line 1158): Verify CLAUDE_CMD_ARGS includes --allowedTools before execution
• Legacy CLI path (line 1173): This path does NOT use --allowedTools - add warning and log
• Live streaming path (line 1100): Verify LIVE_CMD_ARGS preserves --allowedTools from build_claude_command()
• Ensure the flag is not being stripped or modified during array manipulation
• Check if LIVE_CMD_ARGS is properly initialized with CLAUDE_CMD_ARGS values

In the legacy CLI fallback (lines 1169-1180):

• Add a warning log: "Legacy mode does not support --allowedTools, permissions will be interactive"
• Log the fallback reason to help diagnose why modern mode failed
• Consider forcing modern CLI mode when CLAUDE_ALLOWED_TOOLS is set to non-default values
• Prevent fallback to legacy mode if tool permissions are critical
• Add check to ensure Claude CLI version supports --allowedTools before using modern mode

6. Add Validation for Tool Patterns

File: file:ralph_loop.sh

Enhance the validate_allowed_tools() function (lines 537-581):

• Add specific validation for "*" and warn it may not work as "allow all"
• Validate wildcard syntax: Bash(command *) format
• Check for common mistakes: Bash(git*) (missing space) vs Bash(git *)
• Provide helpful error messages with correct syntax examples
• Add validation that wildcards are inside parentheses, not standalone
• Validate that tool names don't have leading/trailing spaces after comma splitting
• Check for unmatched parentheses in tool patterns
• Warn if using colon-based syntax (Bash(git:*)) vs space-based (Bash(git *))

7. Test with Different Claude CLI Versions

File: file:tests/integration/test_allowed_tools.bats

Create integration tests for --allowedTools behavior:

• Test that --allowedTools flag is included in command array
• Test that wildcards are preserved correctly (no shell expansion)
• Test that comma-separated tools are split into separate arguments
• Mock Claude CLI to verify exact arguments received
• Test both modern and legacy CLI paths
• Test that "*" is handled with appropriate warning
• Test that tool patterns with spaces are preserved
• Test that tool patterns without spaces generate warnings
• Verify that LIVE_CMD_ARGS includes --allowedTools flags

8. Add Troubleshooting Guide

File: file:docs/troubleshooting/allowed-tools.md

Create a comprehensive troubleshooting guide:

• Symptom: Permission denied despite setting ALLOWED_TOOLS
• Diagnosis steps:
  1. Enable verbose mode: ralph --verbose
  2. Check logs for actual command executed
  3. Test Claude CLI directly with same flags
  4. Verify Claude CLI version >= 2.0.76
  5. Check if using legacy CLI fallback (indicates modern CLI failed)
  6. Verify wildcard syntax matches Claude CLI expectations
• Common issues:
  • "*" doesn't mean "allow all" - use specific tools or --dangerously-skip-permissions
  • Wildcard syntax must be Bash(git *) not Bash(git*) (space is required)
  • Legacy CLI mode doesn't support --allowedTools (falls back to interactive prompts)
  • Claude CLI version < 2.0.76 may not support --allowedTools flag
  • Colon-based syntax (Bash(git:*)) may not work in all Claude CLI versions
• Solutions: Provide working examples for common scenarios
• Debug output: Explain how to interpret verbose logs to see exact command being executed

9. Update Template Configuration

File: file:lib/enable_core.sh and file:setup.sh

Update the template with better examples and warnings:

• Update default ALLOWED_TOOLS value with inline comments explaining syntax
• Add comments explaining wildcard syntax (space-based: Bash(git *))
• Add warning that "*" is NOT supported as "allow all"
• Provide examples for common development scenarios (git, npm, pytest)
• Add reference to troubleshooting documentation
• Include note about Claude CLI version requirements
• Add example showing how to use --dangerously-skip-permissions if needed

10. Consider Adding Permission Mode Support

File: file:ralph_loop.sh

Add support for Claude CLI's --permission-mode flag:

• New config variable: CLAUDE_PERMISSION_MODE (values: interactive, bypassPermissions)
• When set to bypassPermissions, use --permission-mode bypassPermissions instead of --allowedTools
• Add validation that --allowedTools and --permission-mode bypassPermissions are mutually exclusive
• Document the security implications of each mode
• Add to build_claude_command() to conditionally add --permission-mode flag
• Update .ralphrc template to document this option
• Add validation in validate_allowed_tools() to check for conflicting settings

Investigation Sequence

1. Enable verbose logging to see exact commands being executed
2. Test Claude CLI directly with various --allowedTools patterns to isolate Ralph vs Claude CLI issues
3. Verify wildcard syntax from Claude CLI documentation and test both space-based and colon-based patterns
4. Check all execution paths to ensure flags are passed consistently (modern, legacy, live streaming)
5. Validate tool patterns to catch common mistakes (missing spaces, unmatched parentheses)
6. Document findings in troubleshooting guide with specific examples
7. Implement fixes based on root cause findings (Ralph bug, Claude CLI limitation, or documentation gap)
8. Add tests to prevent regression and verify wildcard patterns work correctly

Expected Outcomes

After implementing these steps, you will have:

1. Visibility: Debug logs showing exact command being executed, including array elements and tool count
2. Verification: Direct Claude CLI tests isolating whether the issue is in Ralph or Claude CLI itself
3. Documentation: Clear guidance on correct wildcard syntax with examples of working and non-working patterns
4. Validation: Enhanced error checking for common mistakes (missing spaces, unmatched parentheses, "*" usage)
5. Alternatives: Support for --permission-mode or --dangerously-skip-permissions as fallback options
6. Troubleshooting: Comprehensive guide for users experiencing this issue with diagnostic steps
7. Tests: Integration tests verifying wildcard patterns work correctly across all execution modes

The investigation will determine whether this is:

• A Ralph implementation bug (incorrect flag passing or array construction)
• A Claude CLI limitation (wildcards not supported as expected, or "*" not meaning "allow all")
• A documentation gap (incorrect usage examples or missing syntax clarification)
• A version compatibility issue (older Claude CLI versions not supporting wildcards)
• A shell escaping issue (wildcards being expanded or modified during command construction)

Import In IDE

🤖 Prompt for AI Agents

## Observations

The issue involves wildcard patterns in `ALLOWED_TOOLS` not working correctly, even when set to `"*"`. The current implementation in `file:ralph_loop.sh` (lines 952-964) correctly splits comma-separated tools and passes each as a separate argument to `--allowedTools`. However, there are several potential root causes: (1) Claude CLI may not support `"*"` as "allow all", (2) wildcard patterns may require specific syntax, (3) the flag may not be passed in all execution paths, or (4) there may be conflicts with permission modes.

The investigation revealed that:
- `build_claude_command()` correctly constructs the command array with `--allowedTools` flags
- `ralph_import.sh` uses array expansion `"${CLAUDE_ALLOWED_TOOLS[@]}"` for proper quoting
- Permission denials are detected via `response_analyzer.sh` which extracts `permission_denials` array from Claude CLI output
- Legacy CLI fallback (line 1173) does NOT pass `--allowedTools`, relying on interactive prompts
- Live streaming mode (line 1100) uses `LIVE_CMD_ARGS` which may not include tool permissions

## Approach

The investigation will follow a systematic debugging approach: first, add comprehensive logging to verify the exact command being executed and confirm `--allowedTools` reaches Claude CLI; second, test Claude CLI directly with various wildcard patterns to isolate whether the issue is in Ralph's implementation or Claude CLI itself; third, verify the correct wildcard syntax and whether Claude CLI supports `"*"` as "allow all"; fourth, ensure `--allowedTools` is passed consistently across all execution modes (live streaming, background, modern vs legacy CLI); and fifth, identify whether the issue is related to how wildcards are escaped or interpreted by the Claude CLI parser. This approach prioritizes verification over speculation and will provide concrete evidence for the root cause.

## Implementation Steps

### 1. Add Debug Logging for Command Verification

**File: `file:ralph_loop.sh`**

In the `build_claude_command()` function (after line 982), add debug logging to print the exact command array being constructed:

- After building `CLAUDE_CMD_ARGS`, add a debug log that prints the full command array
- Use `log_status "DEBUG"` to show each element of the array
- Make this conditional on `VERBOSE_PROGRESS` flag
- Log format: `"Claude CLI command array (${#CLAUDE_CMD_ARGS[@]} elements):"`
- Print each array element with index for visibility
- Include tool count and specific tool names in debug output

In the `execute_claude_code()` function (around lines 1100 and 1158), add logging before executing:

- For live mode (line 1100), log the `LIVE_CMD_ARGS` array before pipeline execution
- For background mode (line 1158), log the `CLAUDE_CMD_ARGS` array before background execution
- Include the exact command that will be executed
- Log whether `--allowedTools` flag is present in the array
- Log the raw `CLAUDE_ALLOWED_TOOLS` value before splitting to detect escaping issues

### 2. Create Test Script for Direct Claude CLI Testing

**New file: `file:tests/manual/test_allowed_tools.sh`**

Create a manual test script to verify Claude CLI behavior directly:

- Test 1: `claude --allowedTools "Write" --allowedTools "Read" -p "list files"` - verify multiple tools work
- Test 2: `claude --allowedTools "*" -p "run git status"` - test if `"*"` is supported
- Test 3: `claude --allowedTools "Bash(git *)" -p "run git commit"` - test wildcard syntax with space
- Test 4: `claude --allowedTools "Bash(git*)" -p "run git status"` - test wildcard without space
- Test 5: `claude --allowedTools "Bash(git:*)" -p "run git status"` - test colon-based wildcard syntax
- Test 6: Compare with `--dangerously-skip-permissions` behavior
- Test 7: Test with `-p` flag vs stdin piping to check mode-specific behavior
- Each test should capture output and check for permission denials
- Document expected vs actual behavior
- Include Claude CLI version check to ensure compatibility

### 3. Verify Wildcard Syntax Documentation

**File: `file:CLAUDE.md`**

Update the documentation section on `ALLOWED_TOOLS` to clarify:

- Document that `"*"` as a standalone value may NOT work as "allow all"
- Clarify that wildcards work WITHIN tool patterns: `Bash(git *)`, not as `"*"`
- Add note that `--dangerously-skip-permissions` is the only way to truly allow all
- Include examples of correct wildcard syntax from Claude CLI docs
- Document the difference between space-based (`Bash(git *)`) and colon-based (`Bash(git:*)`) wildcard syntax
- Add troubleshooting section for permission denials
- Include note about Claude CLI version requirements for wildcard support

### 4. Investigate Alternative "Allow All" Approaches

**File: `file:ralph_loop.sh`**

In the `build_claude_command()` function, add logic to handle special cases:

- If `CLAUDE_ALLOWED_TOOLS` equals `"*"`, log a warning that this may not work as "allow all"
- Suggest using `--dangerously-skip-permissions` instead (with appropriate warnings)
- Consider adding a new config option: `CLAUDE_SKIP_PERMISSIONS=false`
- When enabled, use `--dangerously-skip-permissions` instead of `--allowedTools`
- Document the security implications clearly
- Add validation to prevent both `--allowedTools` and `--dangerously-skip-permissions` from being used simultaneously
- Log which permission mode is being used (allowedTools vs skip-permissions)

### 5. Verify Flag Passing in All Execution Paths

**File: `file:ralph_loop.sh`**

Audit all code paths where Claude CLI is executed:

- **Modern CLI path** (line 1158): Verify `CLAUDE_CMD_ARGS` includes `--allowedTools` before execution
- **Legacy CLI path** (line 1173): This path does NOT use `--allowedTools` - add warning and log
- **Live streaming path** (line 1100): Verify `LIVE_CMD_ARGS` preserves `--allowedTools` from `build_claude_command()`
- Ensure the flag is not being stripped or modified during array manipulation
- Check if `LIVE_CMD_ARGS` is properly initialized with `CLAUDE_CMD_ARGS` values

In the legacy CLI fallback (lines 1169-1180):

- Add a warning log: "Legacy mode does not support --allowedTools, permissions will be interactive"
- Log the fallback reason to help diagnose why modern mode failed
- Consider forcing modern CLI mode when `CLAUDE_ALLOWED_TOOLS` is set to non-default values
- Prevent fallback to legacy mode if tool permissions are critical
- Add check to ensure Claude CLI version supports `--allowedTools` before using modern mode

### 6. Add Validation for Tool Patterns

**File: `file:ralph_loop.sh`**

Enhance the `validate_allowed_tools()` function (lines 537-581):

- Add specific validation for `"*"` and warn it may not work as "allow all"
- Validate wildcard syntax: `Bash(command *)` format
- Check for common mistakes: `Bash(git*)` (missing space) vs `Bash(git *)`
- Provide helpful error messages with correct syntax examples
- Add validation that wildcards are inside parentheses, not standalone
- Validate that tool names don't have leading/trailing spaces after comma splitting
- Check for unmatched parentheses in tool patterns
- Warn if using colon-based syntax (`Bash(git:*)`) vs space-based (`Bash(git *)`)

### 7. Test with Different Claude CLI Versions

**File: `file:tests/integration/test_allowed_tools.bats`**

Create integration tests for `--allowedTools` behavior:

- Test that `--allowedTools` flag is included in command array
- Test that wildcards are preserved correctly (no shell expansion)
- Test that comma-separated tools are split into separate arguments
- Mock Claude CLI to verify exact arguments received
- Test both modern and legacy CLI paths
- Test that `"*"` is handled with appropriate warning
- Test that tool patterns with spaces are preserved
- Test that tool patterns without spaces generate warnings
- Verify that `LIVE_CMD_ARGS` includes `--allowedTools` flags

### 8. Add Troubleshooting Guide

**File: `file:docs/troubleshooting/allowed-tools.md`**

Create a comprehensive troubleshooting guide:

- **Symptom**: Permission denied despite setting `ALLOWED_TOOLS`
- **Diagnosis steps**: 
  1. Enable verbose mode: `ralph --verbose`
  2. Check logs for actual command executed
  3. Test Claude CLI directly with same flags
  4. Verify Claude CLI version >= 2.0.76
  5. Check if using legacy CLI fallback (indicates modern CLI failed)
  6. Verify wildcard syntax matches Claude CLI expectations
- **Common issues**:
  - `"*"` doesn't mean "allow all" - use specific tools or `--dangerously-skip-permissions`
  - Wildcard syntax must be `Bash(git *)` not `Bash(git*)` (space is required)
  - Legacy CLI mode doesn't support `--allowedTools` (falls back to interactive prompts)
  - Claude CLI version < 2.0.76 may not support `--allowedTools` flag
  - Colon-based syntax (`Bash(git:*)`) may not work in all Claude CLI versions
- **Solutions**: Provide working examples for common scenarios
- **Debug output**: Explain how to interpret verbose logs to see exact command being executed

### 9. Update Template Configuration

**File: `file:lib/enable_core.sh` and `file:setup.sh`**

Update the template with better examples and warnings:

- Update default `ALLOWED_TOOLS` value with inline comments explaining syntax
- Add comments explaining wildcard syntax (space-based: `Bash(git *)`)
- Add warning that `"*"` is NOT supported as "allow all"
- Provide examples for common development scenarios (git, npm, pytest)
- Add reference to troubleshooting documentation
- Include note about Claude CLI version requirements
- Add example showing how to use `--dangerously-skip-permissions` if needed

### 10. Consider Adding Permission Mode Support

**File: `file:ralph_loop.sh`**

Add support for Claude CLI's `--permission-mode` flag:

- New config variable: `CLAUDE_PERMISSION_MODE` (values: `interactive`, `bypassPermissions`)
- When set to `bypassPermissions`, use `--permission-mode bypassPermissions` instead of `--allowedTools`
- Add validation that `--allowedTools` and `--permission-mode bypassPermissions` are mutually exclusive
- Document the security implications of each mode
- Add to `build_claude_command()` to conditionally add `--permission-mode` flag
- Update `.ralphrc` template to document this option
- Add validation in `validate_allowed_tools()` to check for conflicting settings

## Investigation Sequence

1. **Enable verbose logging** to see exact commands being executed
2. **Test Claude CLI directly** with various `--allowedTools` patterns to isolate Ralph vs Claude CLI issues
3. **Verify wildcard syntax** from Claude CLI documentation and test both space-based and colon-based patterns
4. **Check all execution paths** to ensure flags are passed consistently (modern, legacy, live streaming)
5. **Validate tool patterns** to catch common mistakes (missing spaces, unmatched parentheses)
6. **Document findings** in troubleshooting guide with specific examples
7. **Implement fixes** based on root cause findings (Ralph bug, Claude CLI limitation, or documentation gap)
8. **Add tests** to prevent regression and verify wildcard patterns work correctly

## Expected Outcomes

After implementing these steps, you will have:

1. **Visibility**: Debug logs showing exact command being executed, including array elements and tool count
2. **Verification**: Direct Claude CLI tests isolating whether the issue is in Ralph or Claude CLI itself
3. **Documentation**: Clear guidance on correct wildcard syntax with examples of working and non-working patterns
4. **Validation**: Enhanced error checking for common mistakes (missing spaces, unmatched parentheses, `"*"` usage)
5. **Alternatives**: Support for `--permission-mode` or `--dangerously-skip-permissions` as fallback options
6. **Troubleshooting**: Comprehensive guide for users experiencing this issue with diagnostic steps
7. **Tests**: Integration tests verifying wildcard patterns work correctly across all execution modes

The investigation will determine whether this is:
- A Ralph implementation bug (incorrect flag passing or array construction)
- A Claude CLI limitation (wildcards not supported as expected, or `"*"` not meaning "allow all")
- A documentation gap (incorrect usage examples or missing syntax clarification)
- A version compatibility issue (older Claude CLI versions not supporting wildcards)
- A shell escaping issue (wildcards being expanded or modified during command construction)

---

Execution Information

Branch: main
Commit: 627ad7d

[tudoanh]

I used this one and it allow all bash calls

ALLOWED_TOOLS="Write,Read,Edit,Bash"

[Lakr233]

Well, I think it is over-engineered in some aspects. I only use this loop with VM, and every time I create a VM, I ask Claude to modify the script to use --yolo. 🤣

[github-actions]

🐛 Triage: Bug

This issue has been labeled as a bug. Wildcard patterns in ALLOWED_TOOLS (e.g., Bash(git *)) not working as expected is a confirmed defect that blocks normal Ralph usage.

Next steps:

• Investigate whether --allowedTools with wildcard/glob patterns is correctly supported by the Claude CLI in non-interactive (-p) mode
• Test with explicit tool names vs. wildcard patterns directly via the Claude CLI to isolate whether this is a Ralph quoting/escaping issue or a Claude CLI limitation
• Check Claude CLI release notes/docs for the correct syntax for allowing bash subcommands

This has been assigned to @frankbria for investigation.

Generated by Issue Triage Assistant

[wtthornton]

Fixed in v2.4.0 (commit incoming).

Root cause: Agent mode (RALPH_USE_AGENT=true, default since v1.8.4) returns early from build_claude_command() without adding --allowedTools. The agent definition uses permissionMode: bypassPermissions with a disallowedTools blocklist — architecturally incompatible with the ALLOWED_TOOLS allowlist.

Fix: Auto-detect when ALLOWED_TOOLS has been customized (differs from template default). When customized:

• Automatically falls back to legacy mode (where --allowedTools works)
• Logs 5 WARN lines explaining why agent mode was disabled and how to use disallowedTools in the agent definition instead

Scenario	Before	After
Default ALLOWED_TOOLS + agent mode	Agent mode, tools ignored	Agent mode (unchanged)
Custom ALLOWED_TOOLS + agent mode	Agent mode, tools silently ignored	Legacy mode + WARN logs
Custom ALLOWED_TOOLS + legacy mode	Legacy mode	Legacy mode (unchanged)

Also updated permission-denied guidance throughout the loop to show agent-mode-specific instructions vs legacy instructions.