[P3] Phase 4.1: Implement CLI enhancement tests

[frankbria]

Description

Create tests for modern CLI enhancements (JSON output, session continuity, etc.).

Test File

tests/unit/test_cli_options.bats

Tests to Implement

• Test JSON output parsing from CLI
• Test sessionId extraction from JSON
• Test session continuity across loops
• Test allowed tools configuration
• Test tool permission enforcement
• Test --continue flag behavior
• Test --output-format flag
• Test --allowedTools flag
• Test error handling with structured JSON responses
• Test backward compatibility with text output

Dependencies

• Requires Phase 1 (CLI enhancements) to be implemented

Acceptance Criteria

• All CLI enhancement features tested
• JSON parsing tests pass
• Session continuity verified
• Tool permissions validated
• Backward compatibility confirmed
• All tests pass in CI/CD

References

• Issue Review codebase for updated Anthropic CLI #7 - Phase 4.1
• Related: Issues [P0] Phase 1.1: Update CLI commands with modern options #28-31 (Phase 1 implementations)

[traycerai]

Plan

Observations

The codebase has a mature BATS testing infrastructure with 75 passing tests covering rate limiting, exit detection, loop execution, and edge cases. The existing CLI in ralph_loop.sh supports flags like --help, --calls, --prompt, --status, --monitor, --verbose, --timeout, --reset-circuit, and --circuit-status. However, the modern CLI enhancements mentioned in issue #39 (JSON output, sessionId extraction, session continuity, allowed tools configuration, --continue, --output-format, --allowedTools flags) are not yet implemented in the codebase. The test helpers provide robust utilities for creating test fixtures and mocking system commands.

Approach

Since the Phase 1 CLI enhancements (issues #28-31) are not yet implemented, the implementation plan must address this critical dependency first. The approach follows a two-stage strategy: Stage 1 implements the missing CLI enhancement features in ralph_loop.sh, and Stage 2 creates comprehensive BATS tests in tests/unit/test_cli_options.bats to validate these features. This ensures tests are written against actual implementations rather than hypothetical functionality, following TDD principles where implementation precedes or accompanies test creation. The plan leverages existing test patterns and existing mock infrastructure.

Implementation Steps

Stage 1: Implement Missing CLI Enhancement Features

1.1 Add JSON Output Support to ralph_loop.sh

Modify the execute_claude_code() function to support structured JSON output format:

• Add new configuration variable OUTPUT_FORMAT="text" (default) in the configuration section (around line 14)
• Add --output-format flag parser in the CLI argument parsing section (around line 631)
• Modify execute_claude_code() to pass format flag to Claude Code CLI: $CLAUDE_CODE_CMD --output-format=$OUTPUT_FORMAT < "$PROMPT_FILE"
• Update analyze_response() calls to handle JSON parsing when OUTPUT_FORMAT="json"
• Create helper function parse_json_response() to extract fields from JSON output
• Validate JSON output format before processing to prevent parsing errors

1.2 Implement Session Continuity

Add session management to maintain context across loops:

• Add SESSION_ID="" variable in configuration section
• Add SESSION_FILE=".ralph_session" to track current session
• Create init_session() function to load or create session ID
• Modify execute_claude_code() to pass --session-id=$SESSION_ID flag to Claude Code
• Extract sessionId from JSON responses and persist to SESSION_FILE
• Add --continue flag to resume previous session
• Implement session validation to ensure session IDs are properly formatted

1.3 Add Allowed Tools Configuration

Implement tool permission management:

• Add ALLOWED_TOOLS="" variable in configuration section
• Add --allowedTools flag parser accepting comma-separated tool list
• Create validate_tools() function to check tool names against whitelist
• Pass --allowed-tools=$ALLOWED_TOOLS to Claude Code CLI
• Add tool permission enforcement in response analysis
• Log tool permission violations for debugging

1.4 Update Help Documentation

Modify show_help() function to document new flags:

• Add --output-format [text|json] description with format details
• Add --continue flag description for session resumption
• Add --allowedTools TOOLS description with examples
• Update examples section with new flag combinations
• Document JSON output schema and session file format

Stage 2: Create Comprehensive Test Suite

2.1 Create Test File Structure

Create tests/unit/test_cli_options.bats with standard BATS structure:

• Add BATS shebang and load test helpers
• Implement setup() function for test initialization
• Implement teardown() function for cleanup
• Source necessary functions from ralph_loop.sh for isolated testing
• Initialize temporary directories for session and configuration files

2.2 JSON Output Tests (3 tests)

Test JSON output parsing functionality:

Test 1: JSON output flag sets OUTPUT_FORMAT variable

• Mock CLI argument parsing with --output-format json
• Assert OUTPUT_FORMAT equals "json"
• Verify flag is properly recognized in argument parser

Test 2: Parse valid JSON response extracts sessionId

• Create fixture JSON response with sessionId field
• Call parse_json_response() function
• Assert extracted sessionId matches expected value
• Verify no data loss during parsing

Test 3: Handle malformed JSON gracefully

• Create fixture with invalid JSON syntax
• Call parse_json_response() with error handling
• Assert function returns error code and logs warning
• Verify graceful degradation without crashing

2.3 Session Continuity Tests (3 tests)

Test session management across loops:

Test 4: init_session creates new session when none exists

• Remove .ralph_session file
• Call init_session()
• Assert new session ID generated and saved to file
• Verify session ID format is valid

Test 5: init_session loads existing session

• Create .ralph_session with known session ID
• Call init_session()
• Assert loaded session ID matches file content
• Verify no session ID regeneration on load

Test 6: --continue flag resumes previous session

• Create .ralph_session with session ID "test-session-123"
• Parse arguments with --continue flag
• Assert SESSION_ID variable equals "test-session-123"
• Verify session persistence across invocations

2.4 Allowed Tools Tests (3 tests)

Test tool permission configuration:

Test 7: --allowedTools flag parses comma-separated list

• Parse arguments with --allowedTools "read_file,write_file,bash"
• Assert ALLOWED_TOOLS contains all three tools
• Verify whitespace handling in tool list

Test 8: validate_tools accepts whitelisted tools

• Set ALLOWED_TOOLS="read_file,write_file"
• Call validate_tools("read_file")
• Assert function returns success (exit code 0)
• Verify tool validation logic

Test 9: validate_tools rejects non-whitelisted tools

• Set ALLOWED_TOOLS="read_file,write_file"
• Call validate_tools("execute_code")
• Assert function returns failure (exit code 1)
• Verify rejection of unauthorized tools

2.5 Flag Behavior Tests (4 tests)

Test CLI flag parsing and interactions:

Test 10: --output-format accepts valid values (text, json)

• Parse arguments with --output-format text and --output-format json
• Assert both are accepted without errors
• Verify format validation

Test 11: --output-format rejects invalid values

• Parse arguments with --output-format xml
• Assert error message displayed and script exits
• Verify error handling for invalid formats

Test 12: Multiple flags combined work correctly

• Parse arguments: --output-format json --continue --allowedTools "read_file"
• Assert all three variables set correctly
• Verify flag interaction and precedence

Test 13: Flag order independence

• Parse arguments in different orders: --continue --output-format json vs --output-format json --continue
• Assert both produce identical configuration
• Verify argument parser robustness

2.6 Error Handling Tests (3 tests)

Test error scenarios with structured responses:

Test 14: JSON error response parsed correctly

• Create fixture JSON with error field: {"error": "API limit reached", "code": 429}
• Call error detection logic
• Assert error extracted and logged appropriately
• Verify error code extraction

Test 15: Missing required JSON fields handled gracefully

• Create JSON response missing sessionId field
• Call parse_json_response()
• Assert function continues without crashing, uses default values
• Verify fallback behavior

Test 16: Empty JSON response handled

• Create fixture with empty JSON object {}
• Call parsing functions
• Assert no crashes, appropriate warnings logged
• Verify empty response handling

2.7 Backward Compatibility Tests (4 tests)

Test compatibility with existing text output:

Test 17: Default output format is text

• Initialize configuration without --output-format flag
• Assert OUTPUT_FORMAT equals "text"
• Verify default behavior preservation

Test 18: Text output parsing still works

• Create fixture with traditional text output
• Call analyze_response() with text format
• Assert analysis completes successfully
• Verify legacy output format support

Test 19: Existing flags unaffected by new features

• Parse arguments: --calls 50 --prompt test.md --verbose
• Assert existing variables (MAX_CALLS_PER_HOUR, PROMPT_FILE, VERBOSE_PROGRESS) set correctly
• Verify no regression in existing functionality

Test 20: Session file optional for backward compatibility

• Remove .ralph_session file
• Run loop without --continue flag
• Assert loop executes normally without session management
• Verify optional session feature

Stage 3: Integration and Validation

3.1 Update Test Helpers

Extend test helper files with new fixtures:

• Create create_sample_json_response() - Generate valid JSON Claude output
• Create create_sample_json_error() - Generate JSON error responses
• Create create_sample_session_file() - Generate session persistence files
• Add helper functions for temporary directory management

3.2 Update CI/CD Pipeline

Ensure GitHub Actions workflow runs new tests:

• Verify BATS discovers test_cli_options.bats automatically
• Add test count validation (should be 75 + 20 = 95 tests)
• Ensure all tests pass before merge
• Add test coverage reporting for new tests

3.3 Documentation Updates

Update project documentation:

• Add new CLI flags to README.md usage section
• Document JSON output schema in CLAUDE.md
• Update IMPLEMENTATION_STATUS.md to mark Phase 4.1 complete
• Create examples showing JSON output and session continuity usage
• Document session file format and structure

Test Execution Flow

Stage 1: Implement CLI Enhancements
  ├─ Add --output-format flag with validation
  ├─ Add --continue flag with session loading
  ├─ Add --allowedTools flag with parsing
  ├─ Implement JSON parsing with error handling
  └─ Implement session management with persistence

Stage 2: Create Test Suite (20 tests)
  ├─ JSON Output Tests (3)
  │  ├─ Test 1: Flag sets OUTPUT_FORMAT
  │  ├─ Test 2: Parse valid JSON response
  │  └─ Test 3: Handle malformed JSON
  ├─ Session Continuity Tests (3)
  │  ├─ Test 4: Create new session
  │  ├─ Test 5: Load existing session
  │  └─ Test 6: Resume with --continue
  ├─ Allowed Tools Tests (3)
  │  ├─ Test 7: Parse tool list
  │  ├─ Test 8: Accept whitelisted tools
  │  └─ Test 9: Reject unauthorized tools
  ├─ Flag Behavior Tests (4)
  │  ├─ Test 10: Accept valid formats
  │  ├─ Test 11: Reject invalid formats
  │  ├─ Test 12: Multiple flags combined
  │  └─ Test 13: Flag order independence
  ├─ Error Handling Tests (3)
  │  ├─ Test 14: Parse JSON errors
  │  ├─ Test 15: Handle missing fields
  │  └─ Test 16: Handle empty responses
  └─ Backward Compatibility Tests (4)
     ├─ Test 17: Default text format
     ├─ Test 18: Text output parsing
     ├─ Test 19: Existing flags work
     └─ Test 20: Optional session file

Stage 3: Integration & Validation
  ├─ Update test helpers with new fixtures
  ├─ Update CI/CD pipeline configuration
  └─ Update documentation

Acceptance Criteria Mapping

Criterion	Implementation Step	Validation
All CLI enhancement features tested	Stages 2.2-2.7	20 tests covering all features
JSON parsing tests pass	Stage 2.2	Tests 1-3 validate JSON handling
Session continuity verified	Stage 2.3	Tests 4-6 validate session management
Tool permissions validated	Stage 2.4	Tests 7-9 validate tool configuration
Backward compatibility confirmed	Stage 2.7	Tests 17-20 ensure existing functionality intact
All tests pass in CI/CD	Stage 3.2	GitHub Actions workflow validates 95 tests

Dependencies and Prerequisites

Critical Dependency: Phase 1 CLI enhancements (issues #28-31) must be implemented first. This plan assumes Stage 1 implementation is completed before Stage 2 test creation.

Required Tools:

• BATS testing framework (already installed per package.json)
• jq for JSON parsing (required for JSON output tests)
• Existing test infrastructure

Existing Resources:

• Test patterns from existing BATS test files
• Mock infrastructure in test helpers
• Fixture generators in test helpers

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a mature BATS testing infrastructure with 75 passing tests covering rate limiting, exit detection, loop execution, and edge cases. The existing CLI in `ralph_loop.sh` supports flags like `--help`, `--calls`, `--prompt`, `--status`, `--monitor`, `--verbose`, `--timeout`, `--reset-circuit`, and `--circuit-status`. However, the modern CLI enhancements mentioned in issue #39 (JSON output, sessionId extraction, session continuity, allowed tools configuration, `--continue`, `--output-format`, `--allowedTools` flags) are **not yet implemented** in the codebase. The test helpers provide robust utilities for creating test fixtures and mocking system commands.

## Approach

Since the Phase 1 CLI enhancements (issues #28-31) are not yet implemented, the implementation plan must address this critical dependency first. The approach follows a two-stage strategy: **Stage 1** implements the missing CLI enhancement features in `ralph_loop.sh`, and **Stage 2** creates comprehensive BATS tests in `tests/unit/test_cli_options.bats` to validate these features. This ensures tests are written against actual implementations rather than hypothetical functionality, following TDD principles where implementation precedes or accompanies test creation. The plan leverages existing test patterns and existing mock infrastructure.

## Implementation Steps

### Stage 1: Implement Missing CLI Enhancement Features

#### 1.1 Add JSON Output Support to ralph_loop.sh

Modify the `execute_claude_code()` function to support structured JSON output format:

- Add new configuration variable `OUTPUT_FORMAT="text"` (default) in the configuration section (around line 14)
- Add `--output-format` flag parser in the CLI argument parsing section (around line 631)
- Modify `execute_claude_code()` to pass format flag to Claude Code CLI: `$CLAUDE_CODE_CMD --output-format=$OUTPUT_FORMAT < "$PROMPT_FILE"`
- Update `analyze_response()` calls to handle JSON parsing when `OUTPUT_FORMAT="json"`
- Create helper function `parse_json_response()` to extract fields from JSON output
- Validate JSON output format before processing to prevent parsing errors

#### 1.2 Implement Session Continuity

Add session management to maintain context across loops:

- Add `SESSION_ID=""` variable in configuration section
- Add `SESSION_FILE=".ralph_session"` to track current session
- Create `init_session()` function to load or create session ID
- Modify `execute_claude_code()` to pass `--session-id=$SESSION_ID` flag to Claude Code
- Extract `sessionId` from JSON responses and persist to `SESSION_FILE`
- Add `--continue` flag to resume previous session
- Implement session validation to ensure session IDs are properly formatted

#### 1.3 Add Allowed Tools Configuration

Implement tool permission management:

- Add `ALLOWED_TOOLS=""` variable in configuration section
- Add `--allowedTools` flag parser accepting comma-separated tool list
- Create `validate_tools()` function to check tool names against whitelist
- Pass `--allowed-tools=$ALLOWED_TOOLS` to Claude Code CLI
- Add tool permission enforcement in response analysis
- Log tool permission violations for debugging

#### 1.4 Update Help Documentation

Modify `show_help()` function to document new flags:

- Add `--output-format [text|json]` description with format details
- Add `--continue` flag description for session resumption
- Add `--allowedTools TOOLS` description with examples
- Update examples section with new flag combinations
- Document JSON output schema and session file format

### Stage 2: Create Comprehensive Test Suite

#### 2.1 Create Test File Structure

Create `tests/unit/test_cli_options.bats` with standard BATS structure:

- Add BATS shebang and load test helpers
- Implement `setup()` function for test initialization
- Implement `teardown()` function for cleanup
- Source necessary functions from `ralph_loop.sh` for isolated testing
- Initialize temporary directories for session and configuration files

#### 2.2 JSON Output Tests (3 tests)

Test JSON output parsing functionality:

**Test 1: JSON output flag sets OUTPUT_FORMAT variable**
- Mock CLI argument parsing with `--output-format json`
- Assert `OUTPUT_FORMAT` equals "json"
- Verify flag is properly recognized in argument parser

**Test 2: Parse valid JSON response extracts sessionId**
- Create fixture JSON response with `sessionId` field
- Call `parse_json_response()` function
- Assert extracted sessionId matches expected value
- Verify no data loss during parsing

**Test 3: Handle malformed JSON gracefully**
- Create fixture with invalid JSON syntax
- Call `parse_json_response()` with error handling
- Assert function returns error code and logs warning
- Verify graceful degradation without crashing

#### 2.3 Session Continuity Tests (3 tests)

Test session management across loops:

**Test 4: init_session creates new session when none exists**
- Remove `.ralph_session` file
- Call `init_session()`
- Assert new session ID generated and saved to file
- Verify session ID format is valid

**Test 5: init_session loads existing session**
- Create `.ralph_session` with known session ID
- Call `init_session()`
- Assert loaded session ID matches file content
- Verify no session ID regeneration on load

**Test 6: --continue flag resumes previous session**
- Create `.ralph_session` with session ID "test-session-123"
- Parse arguments with `--continue` flag
- Assert `SESSION_ID` variable equals "test-session-123"
- Verify session persistence across invocations

#### 2.4 Allowed Tools Tests (3 tests)

Test tool permission configuration:

**Test 7: --allowedTools flag parses comma-separated list**
- Parse arguments with `--allowedTools "read_file,write_file,bash"`
- Assert `ALLOWED_TOOLS` contains all three tools
- Verify whitespace handling in tool list

**Test 8: validate_tools accepts whitelisted tools**
- Set `ALLOWED_TOOLS="read_file,write_file"`
- Call `validate_tools("read_file")`
- Assert function returns success (exit code 0)
- Verify tool validation logic

**Test 9: validate_tools rejects non-whitelisted tools**
- Set `ALLOWED_TOOLS="read_file,write_file"`
- Call `validate_tools("execute_code")`
- Assert function returns failure (exit code 1)
- Verify rejection of unauthorized tools

#### 2.5 Flag Behavior Tests (4 tests)

Test CLI flag parsing and interactions:

**Test 10: --output-format accepts valid values (text, json)**
- Parse arguments with `--output-format text` and `--output-format json`
- Assert both are accepted without errors
- Verify format validation

**Test 11: --output-format rejects invalid values**
- Parse arguments with `--output-format xml`
- Assert error message displayed and script exits
- Verify error handling for invalid formats

**Test 12: Multiple flags combined work correctly**
- Parse arguments: `--output-format json --continue --allowedTools "read_file"`
- Assert all three variables set correctly
- Verify flag interaction and precedence

**Test 13: Flag order independence**
- Parse arguments in different orders: `--continue --output-format json` vs `--output-format json --continue`
- Assert both produce identical configuration
- Verify argument parser robustness

#### 2.6 Error Handling Tests (3 tests)

Test error scenarios with structured responses:

**Test 14: JSON error response parsed correctly**
- Create fixture JSON with error field: `{"error": "API limit reached", "code": 429}`
- Call error detection logic
- Assert error extracted and logged appropriately
- Verify error code extraction

**Test 15: Missing required JSON fields handled gracefully**
- Create JSON response missing `sessionId` field
- Call `parse_json_response()`
- Assert function continues without crashing, uses default values
- Verify fallback behavior

**Test 16: Empty JSON response handled**
- Create fixture with empty JSON object `{}`
- Call parsing functions
- Assert no crashes, appropriate warnings logged
- Verify empty response handling

#### 2.7 Backward Compatibility Tests (4 tests)

Test compatibility with existing text output:

**Test 17: Default output format is text**
- Initialize configuration without `--output-format` flag
- Assert `OUTPUT_FORMAT` equals "text"
- Verify default behavior preservation

**Test 18: Text output parsing still works**
- Create fixture with traditional text output
- Call `analyze_response()` with text format
- Assert analysis completes successfully
- Verify legacy output format support

**Test 19: Existing flags unaffected by new features**
- Parse arguments: `--calls 50 --prompt test.md --verbose`
- Assert existing variables (`MAX_CALLS_PER_HOUR`, `PROMPT_FILE`, `VERBOSE_PROGRESS`) set correctly
- Verify no regression in existing functionality

**Test 20: Session file optional for backward compatibility**
- Remove `.ralph_session` file
- Run loop without `--continue` flag
- Assert loop executes normally without session management
- Verify optional session feature

### Stage 3: Integration and Validation

#### 3.1 Update Test Helpers

Extend test helper files with new fixtures:

- Create `create_sample_json_response()` - Generate valid JSON Claude output
- Create `create_sample_json_error()` - Generate JSON error responses
- Create `create_sample_session_file()` - Generate session persistence files
- Add helper functions for temporary directory management

#### 3.2 Update CI/CD Pipeline

Ensure GitHub Actions workflow runs new tests:

- Verify BATS discovers `test_cli_options.bats` automatically
- Add test count validation (should be 75 + 20 = 95 tests)
- Ensure all tests pass before merge
- Add test coverage reporting for new tests

#### 3.3 Documentation Updates

Update project documentation:

- Add new CLI flags to `README.md` usage section
- Document JSON output schema in `CLAUDE.md`
- Update `IMPLEMENTATION_STATUS.md` to mark Phase 4.1 complete
- Create examples showing JSON output and session continuity usage
- Document session file format and structure

## Test Execution Flow

```
Stage 1: Implement CLI Enhancements
  ├─ Add --output-format flag with validation
  ├─ Add --continue flag with session loading
  ├─ Add --allowedTools flag with parsing
  ├─ Implement JSON parsing with error handling
  └─ Implement session management with persistence

Stage 2: Create Test Suite (20 tests)
  ├─ JSON Output Tests (3)
  │  ├─ Test 1: Flag sets OUTPUT_FORMAT
  │  ├─ Test 2: Parse valid JSON response
  │  └─ Test 3: Handle malformed JSON
  ├─ Session Continuity Tests (3)
  │  ├─ Test 4: Create new session
  │  ├─ Test 5: Load existing session
  │  └─ Test 6: Resume with --continue
  ├─ Allowed Tools Tests (3)
  │  ├─ Test 7: Parse tool list
  │  ├─ Test 8: Accept whitelisted tools
  │  └─ Test 9: Reject unauthorized tools
  ├─ Flag Behavior Tests (4)
  │  ├─ Test 10: Accept valid formats
  │  ├─ Test 11: Reject invalid formats
  │  ├─ Test 12: Multiple flags combined
  │  └─ Test 13: Flag order independence
  ├─ Error Handling Tests (3)
  │  ├─ Test 14: Parse JSON errors
  │  ├─ Test 15: Handle missing fields
  │  └─ Test 16: Handle empty responses
  └─ Backward Compatibility Tests (4)
     ├─ Test 17: Default text format
     ├─ Test 18: Text output parsing
     ├─ Test 19: Existing flags work
     └─ Test 20: Optional session file

Stage 3: Integration & Validation
  ├─ Update test helpers with new fixtures
  ├─ Update CI/CD pipeline configuration
  └─ Update documentation
```

## Acceptance Criteria Mapping

| Criterion | Implementation Step | Validation |
|-----------|-------------------|------------|
| All CLI enhancement features tested | Stages 2.2-2.7 | 20 tests covering all features |
| JSON parsing tests pass | Stage 2.2 | Tests 1-3 validate JSON handling |
| Session continuity verified | Stage 2.3 | Tests 4-6 validate session management |
| Tool permissions validated | Stage 2.4 | Tests 7-9 validate tool configuration |
| Backward compatibility confirmed | Stage 2.7 | Tests 17-20 ensure existing functionality intact |
| All tests pass in CI/CD | Stage 3.2 | GitHub Actions workflow validates 95 tests |

## Dependencies and Prerequisites

**Critical Dependency**: Phase 1 CLI enhancements (issues #28-31) must be implemented first. This plan assumes Stage 1 implementation is completed before Stage 2 test creation.

**Required Tools**:
- BATS testing framework (already installed per package.json)
- jq for JSON parsing (required for JSON output tests)
- Existing test infrastructure

**Existing Resources**:
- Test patterns from existing BATS test files
- Mock infrastructure in test helpers
- Fixture generators in test helpers

---

Execution Information

Branch: main
Commit: 870181b

---

💡 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

---

🔗 Similar Issues

Related Issues

• [P0] Phase 1.1: Update CLI commands with modern options #28
• [P0] Implement CLI parsing tests (Week 2) #10
• [P1] Phase 1.4: Update ralph-import with CLI enhancements #31
• [P1] Phase 1.2: Enhance response parsing for JSON output #29
• [P2] Phase 4.6: Implement status update tests #16
• [P3] Phase 3.3: Create CLI and SDK documentation #38

👤 Suggested Assignees

• frankbria

---

🧪 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 codebase has a mature BATS testing infrastructure with 75 passing tests covering rate limiting, exit detection, loop execution, and edge cases. The existing CLI in file:ralph_loop.sh supports flags like --help, --calls, --prompt, --status, --monitor, --verbose, --timeout, --reset-circuit, and --circuit-status. However, the modern CLI enhancements mentioned in issue #39 (JSON output, sessionId extraction, session continuity, allowed tools configuration, --continue, --output-format, --allowedTools flags) are not yet implemented in the codebase. The test helpers (file:tests/helpers/test_helper.bash, file:tests/helpers/mocks.bash, file:tests/helpers/fixtures.bash) provide robust utilities for creating test fixtures and mocking system commands.

Approach

Since the Phase 1 CLI enhancements (issues #28-31) are not yet implemented, the implementation plan must address this critical dependency first. The approach follows a two-stage strategy: Stage 1 implements the missing CLI enhancement features in ralph_loop.sh, and Stage 2 creates comprehensive BATS tests in file:tests/unit/test_cli_options.bats to validate these features. This ensures tests are written against actual implementations rather than hypothetical functionality, following TDD principles where implementation precedes or accompanies test creation. The plan leverages existing test patterns from file:tests/unit/test_exit_detection.bats and existing mock infrastructure.

Implementation Steps

Stage 1: Implement Missing CLI Enhancement Features

1.1 Add JSON Output Support to ralph_loop.sh

Modify the execute_claude_code() function to support structured JSON output format:

• Add new configuration variable OUTPUT_FORMAT="text" (default) in the configuration section (around line 14)
• Add --output-format flag parser in the CLI argument parsing section (around line 631)
• Modify execute_claude_code() to pass format flag to Claude Code CLI: $CLAUDE_CODE_CMD --output-format=$OUTPUT_FORMAT < "$PROMPT_FILE"
• Update analyze_response() calls to handle JSON parsing when OUTPUT_FORMAT="json"
• Create helper function parse_json_response() to extract fields from JSON output

1.2 Implement Session Continuity

Add session management to maintain context across loops:

• Add SESSION_ID="" variable in configuration section
• Add SESSION_FILE=".ralph_session" to track current session
• Create init_session() function to load or create session ID
• Modify execute_claude_code() to pass --session-id=$SESSION_ID flag to Claude Code
• Extract sessionId from JSON responses and persist to SESSION_FILE
• Add --continue flag to resume previous session

1.3 Add Allowed Tools Configuration

Implement tool permission management:

• Add ALLOWED_TOOLS="" variable in configuration section
• Add --allowedTools flag parser accepting comma-separated tool list
• Create validate_tools() function to check tool names against whitelist
• Pass --allowed-tools=$ALLOWED_TOOLS to Claude Code CLI
• Add tool permission enforcement in response analysis

1.4 Update Help Documentation

Modify show_help() function to document new flags:

• Add --output-format [text|json] description
• Add --continue flag description for session resumption
• Add --allowedTools TOOLS description with examples
• Update examples section with new flag combinations

Stage 2: Create Comprehensive Test Suite

2.1 Create Test File Structure

Create file:tests/unit/test_cli_options.bats with standard BATS structure:

• Add BATS shebang and load test helpers
• Implement setup() function using patterns from file:tests/unit/test_exit_detection.bats
• Implement teardown() function for cleanup
• Source necessary functions from ralph_loop.sh for isolated testing

2.2 JSON Output Tests (3 tests)

Test JSON output parsing functionality:

Test 1: JSON output flag sets OUTPUT_FORMAT variable

• Mock CLI argument parsing with --output-format json
• Assert OUTPUT_FORMAT equals "json"

Test 2: Parse valid JSON response extracts sessionId

• Create fixture JSON response with sessionId field using file:tests/helpers/fixtures.bash pattern
• Call parse_json_response() function
• Assert extracted sessionId matches expected value

Test 3: Handle malformed JSON gracefully

• Create fixture with invalid JSON syntax
• Call parse_json_response() with error handling
• Assert function returns error code and logs warning

2.3 Session Continuity Tests (3 tests)

Test session management across loops:

Test 4: init_session creates new session when none exists

• Remove .ralph_session file
• Call init_session()
• Assert new session ID generated and saved to file

Test 5: init_session loads existing session

• Create .ralph_session with known session ID
• Call init_session()
• Assert loaded session ID matches file content

Test 6: --continue flag resumes previous session

• Create .ralph_session with session ID "test-session-123"
• Parse arguments with --continue flag
• Assert SESSION_ID variable equals "test-session-123"

2.4 Allowed Tools Tests (3 tests)

Test tool permission configuration:

Test 7: --allowedTools flag parses comma-separated list

• Parse arguments with --allowedTools "read_file,write_file,bash"
• Assert ALLOWED_TOOLS contains all three tools

Test 8: validate_tools accepts whitelisted tools

• Set ALLOWED_TOOLS="read_file,write_file"
• Call validate_tools("read_file")
• Assert function returns success (exit code 0)

Test 9: validate_tools rejects non-whitelisted tools

• Set ALLOWED_TOOLS="read_file,write_file"
• Call validate_tools("execute_code")
• Assert function returns failure (exit code 1)

2.5 Flag Behavior Tests (4 tests)

Test CLI flag parsing and interactions:

Test 10: --output-format accepts valid values (text, json)

• Parse arguments with --output-format text and --output-format json
• Assert both are accepted without errors

Test 11: --output-format rejects invalid values

• Parse arguments with --output-format xml
• Assert error message displayed and script exits

Test 12: Multiple flags combined work correctly

• Parse arguments: --output-format json --continue --allowedTools "read_file"
• Assert all three variables set correctly

Test 13: Flag order independence

• Parse arguments in different orders: --continue --output-format json vs --output-format json --continue
• Assert both produce identical configuration

2.6 Error Handling Tests (3 tests)

Test error scenarios with structured responses:

Test 14: JSON error response parsed correctly

• Create fixture JSON with error field: {"error": "API limit reached", "code": 429}
• Call error detection logic
• Assert error extracted and logged appropriately

Test 15: Missing required JSON fields handled gracefully

• Create JSON response missing sessionId field
• Call parse_json_response()
• Assert function continues without crashing, uses default values

Test 16: Empty JSON response handled

• Create fixture with empty JSON object {}
• Call parsing functions
• Assert no crashes, appropriate warnings logged

2.7 Backward Compatibility Tests (4 tests)

Test compatibility with existing text output:

Test 17: Default output format is text

• Initialize configuration without --output-format flag
• Assert OUTPUT_FORMAT equals "text"

Test 18: Text output parsing still works

• Create fixture with traditional text output (from file:tests/helpers/fixtures.bash)
• Call analyze_response() with text format
• Assert analysis completes successfully

Test 19: Existing flags unaffected by new features

• Parse arguments: --calls 50 --prompt test.md --verbose
• Assert existing variables (MAX_CALLS_PER_HOUR, PROMPT_FILE, VERBOSE_PROGRESS) set correctly

Test 20: Session file optional for backward compatibility

• Remove .ralph_session file
• Run loop without --continue flag
• Assert loop executes normally without session management

Stage 3: Integration and Validation

3.1 Update Test Helpers

Extend file:tests/helpers/fixtures.bash with new fixtures:

• create_sample_json_response() - Generate valid JSON Claude output
• create_sample_json_error() - Generate JSON error responses
• create_sample_session_file() - Generate session persistence files

3.2 Update CI/CD Pipeline

Ensure file:.github/workflows/test.yml runs new tests:

• Verify BATS discovers test_cli_options.bats automatically
• Add test count validation (should be 75 + 20 = 95 tests)
• Ensure all tests pass before merge

3.3 Documentation Updates

Update project documentation:

• Add new CLI flags to file:README.md usage section
• Document JSON output schema in file:CLAUDE.md
• Update file:IMPLEMENTATION_STATUS.md to mark Phase 4.1 complete
• Create examples showing JSON output and session continuity usage

Test Execution Flow

sequenceDiagram
    participant Dev as Developer
    participant Impl as ralph_loop.sh
    participant Tests as test_cli_options.bats
    participant CI as GitHub Actions

    Dev->>Impl: Stage 1: Implement CLI enhancements
    Impl->>Impl: Add --output-format flag
    Impl->>Impl: Add --continue flag
    Impl->>Impl: Add --allowedTools flag
    Impl->>Impl: Implement JSON parsing
    Impl->>Impl: Implement session management
    
    Dev->>Tests: Stage 2: Create test suite
    Tests->>Tests: Write 20 tests covering all features
    Tests->>Impl: Test JSON output parsing
    Tests->>Impl: Test session continuity
    Tests->>Impl: Test tool permissions
    Tests->>Impl: Test backward compatibility
    
    Dev->>CI: Stage 3: Run full test suite
    CI->>Tests: Execute all 95 tests (75 existing + 20 new)
    Tests-->>CI: Report results
    CI-->>Dev: ✅ All tests pass

Loading

Acceptance Criteria Mapping

Criterion	Implementation Step	Validation
All CLI enhancement features tested	Steps 2.2-2.7	20 tests covering all features
JSON parsing tests pass	Step 2.2	Tests 1-3 validate JSON handling
Session continuity verified	Step 2.3	Tests 4-6 validate session management
Tool permissions validated	Step 2.4	Tests 7-9 validate tool configuration
Backward compatibility confirmed	Step 2.7	Tests 17-20 ensure existing functionality intact
All tests pass in CI/CD	Step 3.2	GitHub Actions workflow validates 95 tests

Dependencies and Prerequisites

Critical Dependency: Phase 1 CLI enhancements (issues #28-31) must be implemented first. This plan assumes Stage 1 implementation is completed before Stage 2 test creation.

Required Tools:

• BATS testing framework (already installed per file:package.json)
• jq for JSON parsing (required for JSON output tests)
• Existing test infrastructure (file:tests/helpers/)

Existing Resources:

• Test patterns from file:tests/unit/test_exit_detection.bats
• Mock infrastructure in file:tests/helpers/mocks.bash
• Fixture generators in file:tests/helpers/fixtures.bash

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a mature BATS testing infrastructure with 75 passing tests covering rate limiting, exit detection, loop execution, and edge cases. The existing CLI in `file:ralph_loop.sh` supports flags like `--help`, `--calls`, `--prompt`, `--status`, `--monitor`, `--verbose`, `--timeout`, `--reset-circuit`, and `--circuit-status`. However, the modern CLI enhancements mentioned in issue #39 (JSON output, sessionId extraction, session continuity, allowed tools configuration, `--continue`, `--output-format`, `--allowedTools` flags) are **not yet implemented** in the codebase. The test helpers (`file:tests/helpers/test_helper.bash`, `file:tests/helpers/mocks.bash`, `file:tests/helpers/fixtures.bash`) provide robust utilities for creating test fixtures and mocking system commands.

## Approach

Since the Phase 1 CLI enhancements (issues #28-31) are not yet implemented, the implementation plan must address this critical dependency first. The approach follows a two-stage strategy: **Stage 1** implements the missing CLI enhancement features in `ralph_loop.sh`, and **Stage 2** creates comprehensive BATS tests in `file:tests/unit/test_cli_options.bats` to validate these features. This ensures tests are written against actual implementations rather than hypothetical functionality, following TDD principles where implementation precedes or accompanies test creation. The plan leverages existing test patterns from `file:tests/unit/test_exit_detection.bats` and existing mock infrastructure.

## Implementation Steps

### Stage 1: Implement Missing CLI Enhancement Features

#### 1.1 Add JSON Output Support to ralph_loop.sh

Modify the `execute_claude_code()` function to support structured JSON output format:

- Add new configuration variable `OUTPUT_FORMAT="text"` (default) in the configuration section (around line 14)
- Add `--output-format` flag parser in the CLI argument parsing section (around line 631)
- Modify `execute_claude_code()` to pass format flag to Claude Code CLI: `$CLAUDE_CODE_CMD --output-format=$OUTPUT_FORMAT < "$PROMPT_FILE"`
- Update `analyze_response()` calls to handle JSON parsing when `OUTPUT_FORMAT="json"`
- Create helper function `parse_json_response()` to extract fields from JSON output

#### 1.2 Implement Session Continuity

Add session management to maintain context across loops:

- Add `SESSION_ID=""` variable in configuration section
- Add `SESSION_FILE=".ralph_session"` to track current session
- Create `init_session()` function to load or create session ID
- Modify `execute_claude_code()` to pass `--session-id=$SESSION_ID` flag to Claude Code
- Extract `sessionId` from JSON responses and persist to `SESSION_FILE`
- Add `--continue` flag to resume previous session

#### 1.3 Add Allowed Tools Configuration

Implement tool permission management:

- Add `ALLOWED_TOOLS=""` variable in configuration section
- Add `--allowedTools` flag parser accepting comma-separated tool list
- Create `validate_tools()` function to check tool names against whitelist
- Pass `--allowed-tools=$ALLOWED_TOOLS` to Claude Code CLI
- Add tool permission enforcement in response analysis

#### 1.4 Update Help Documentation

Modify `show_help()` function to document new flags:

- Add `--output-format [text|json]` description
- Add `--continue` flag description for session resumption
- Add `--allowedTools TOOLS` description with examples
- Update examples section with new flag combinations

### Stage 2: Create Comprehensive Test Suite

#### 2.1 Create Test File Structure

Create `file:tests/unit/test_cli_options.bats` with standard BATS structure:

- Add BATS shebang and load test helpers
- Implement `setup()` function using patterns from `file:tests/unit/test_exit_detection.bats`
- Implement `teardown()` function for cleanup
- Source necessary functions from `ralph_loop.sh` for isolated testing

#### 2.2 JSON Output Tests (3 tests)

Test JSON output parsing functionality:

**Test 1: JSON output flag sets OUTPUT_FORMAT variable**
- Mock CLI argument parsing with `--output-format json`
- Assert `OUTPUT_FORMAT` equals "json"

**Test 2: Parse valid JSON response extracts sessionId**
- Create fixture JSON response with `sessionId` field using `file:tests/helpers/fixtures.bash` pattern
- Call `parse_json_response()` function
- Assert extracted sessionId matches expected value

**Test 3: Handle malformed JSON gracefully**
- Create fixture with invalid JSON syntax
- Call `parse_json_response()` with error handling
- Assert function returns error code and logs warning

#### 2.3 Session Continuity Tests (3 tests)

Test session management across loops:

**Test 4: init_session creates new session when none exists**
- Remove `.ralph_session` file
- Call `init_session()`
- Assert new session ID generated and saved to file

**Test 5: init_session loads existing session**
- Create `.ralph_session` with known session ID
- Call `init_session()`
- Assert loaded session ID matches file content

**Test 6: --continue flag resumes previous session**
- Create `.ralph_session` with session ID "test-session-123"
- Parse arguments with `--continue` flag
- Assert `SESSION_ID` variable equals "test-session-123"

#### 2.4 Allowed Tools Tests (3 tests)

Test tool permission configuration:

**Test 7: --allowedTools flag parses comma-separated list**
- Parse arguments with `--allowedTools "read_file,write_file,bash"`
- Assert `ALLOWED_TOOLS` contains all three tools

**Test 8: validate_tools accepts whitelisted tools**
- Set `ALLOWED_TOOLS="read_file,write_file"`
- Call `validate_tools("read_file")`
- Assert function returns success (exit code 0)

**Test 9: validate_tools rejects non-whitelisted tools**
- Set `ALLOWED_TOOLS="read_file,write_file"`
- Call `validate_tools("execute_code")`
- Assert function returns failure (exit code 1)

#### 2.5 Flag Behavior Tests (4 tests)

Test CLI flag parsing and interactions:

**Test 10: --output-format accepts valid values (text, json)**
- Parse arguments with `--output-format text` and `--output-format json`
- Assert both are accepted without errors

**Test 11: --output-format rejects invalid values**
- Parse arguments with `--output-format xml`
- Assert error message displayed and script exits

**Test 12: Multiple flags combined work correctly**
- Parse arguments: `--output-format json --continue --allowedTools "read_file"`
- Assert all three variables set correctly

**Test 13: Flag order independence**
- Parse arguments in different orders: `--continue --output-format json` vs `--output-format json --continue`
- Assert both produce identical configuration

#### 2.6 Error Handling Tests (3 tests)

Test error scenarios with structured responses:

**Test 14: JSON error response parsed correctly**
- Create fixture JSON with error field: `{"error": "API limit reached", "code": 429}`
- Call error detection logic
- Assert error extracted and logged appropriately

**Test 15: Missing required JSON fields handled gracefully**
- Create JSON response missing `sessionId` field
- Call `parse_json_response()`
- Assert function continues without crashing, uses default values

**Test 16: Empty JSON response handled**
- Create fixture with empty JSON object `{}`
- Call parsing functions
- Assert no crashes, appropriate warnings logged

#### 2.7 Backward Compatibility Tests (4 tests)

Test compatibility with existing text output:

**Test 17: Default output format is text**
- Initialize configuration without `--output-format` flag
- Assert `OUTPUT_FORMAT` equals "text"

**Test 18: Text output parsing still works**
- Create fixture with traditional text output (from `file:tests/helpers/fixtures.bash`)
- Call `analyze_response()` with text format
- Assert analysis completes successfully

**Test 19: Existing flags unaffected by new features**
- Parse arguments: `--calls 50 --prompt test.md --verbose`
- Assert existing variables (`MAX_CALLS_PER_HOUR`, `PROMPT_FILE`, `VERBOSE_PROGRESS`) set correctly

**Test 20: Session file optional for backward compatibility**
- Remove `.ralph_session` file
- Run loop without `--continue` flag
- Assert loop executes normally without session management

### Stage 3: Integration and Validation

#### 3.1 Update Test Helpers

Extend `file:tests/helpers/fixtures.bash` with new fixtures:

- `create_sample_json_response()` - Generate valid JSON Claude output
- `create_sample_json_error()` - Generate JSON error responses
- `create_sample_session_file()` - Generate session persistence files

#### 3.2 Update CI/CD Pipeline

Ensure `file:.github/workflows/test.yml` runs new tests:

- Verify BATS discovers `test_cli_options.bats` automatically
- Add test count validation (should be 75 + 20 = 95 tests)
- Ensure all tests pass before merge

#### 3.3 Documentation Updates

Update project documentation:

- Add new CLI flags to `file:README.md` usage section
- Document JSON output schema in `file:CLAUDE.md`
- Update `file:IMPLEMENTATION_STATUS.md` to mark Phase 4.1 complete
- Create examples showing JSON output and session continuity usage

## Test Execution Flow

```mermaid
sequenceDiagram
    participant Dev as Developer
    participant Impl as ralph_loop.sh
    participant Tests as test_cli_options.bats
    participant CI as GitHub Actions

    Dev->>Impl: Stage 1: Implement CLI enhancements
    Impl->>Impl: Add --output-format flag
    Impl->>Impl: Add --continue flag
    Impl->>Impl: Add --allowedTools flag
    Impl->>Impl: Implement JSON parsing
    Impl->>Impl: Implement session management
    
    Dev->>Tests: Stage 2: Create test suite
    Tests->>Tests: Write 20 tests covering all features
    Tests->>Impl: Test JSON output parsing
    Tests->>Impl: Test session continuity
    Tests->>Impl: Test tool permissions
    Tests->>Impl: Test backward compatibility
    
    Dev->>CI: Stage 3: Run full test suite
    CI->>Tests: Execute all 95 tests (75 existing + 20 new)
    Tests-->>CI: Report results
    CI-->>Dev: ✅ All tests pass
```

## Acceptance Criteria Mapping

| Criterion | Implementation Step | Validation |
|-----------|-------------------|------------|
| All CLI enhancement features tested | Steps 2.2-2.7 | 20 tests covering all features |
| JSON parsing tests pass | Step 2.2 | Tests 1-3 validate JSON handling |
| Session continuity verified | Step 2.3 | Tests 4-6 validate session management |
| Tool permissions validated | Step 2.4 | Tests 7-9 validate tool configuration |
| Backward compatibility confirmed | Step 2.7 | Tests 17-20 ensure existing functionality intact |
| All tests pass in CI/CD | Step 3.2 | GitHub Actions workflow validates 95 tests |

## Dependencies and Prerequisites

**Critical Dependency**: Phase 1 CLI enhancements (issues #28-31) must be implemented first. This plan assumes Stage 1 implementation is completed before Stage 2 test creation.

**Required Tools**:
- BATS testing framework (already installed per `file:package.json`)
- jq for JSON parsing (required for JSON output tests)
- Existing test infrastructure (`file:tests/helpers/`)

**Existing Resources**:
- Test patterns from `file:tests/unit/test_exit_detection.bats`
- Mock infrastructure in `file:tests/helpers/mocks.bash`
- Fixture generators in `file:tests/helpers/fixtures.bash`

---

Execution Information

Branch: main
Commit: 3b4f5f0

New Plan

Observations

The codebase has a mature BATS testing infrastructure with 75 passing tests covering rate limiting, exit detection, loop execution, and edge cases. The existing CLI in ralph_loop.sh supports flags like --help, --calls, --prompt, --status, --monitor, --verbose, --timeout, --reset-circuit, and --circuit-status. However, the modern CLI enhancements mentioned in issue #39 (JSON output, sessionId extraction, session continuity, allowed tools configuration, --continue, --output-format, --allowedTools flags) are not yet implemented in the codebase. The test helpers provide robust utilities for creating test fixtures and mocking system commands.

Approach

Since the Phase 1 CLI enhancements (issues #28-31) are not yet implemented, the implementation plan must address this critical dependency first. The approach follows a two-stage strategy: Stage 1 implements the missing CLI enhancement features in ralph_loop.sh, and Stage 2 creates comprehensive BATS tests in tests/unit/test_cli_options.bats to validate these features. This ensures tests are written against actual implementations rather than hypothetical functionality, following TDD principles where implementation precedes or accompanies test creation. The plan leverages existing test patterns and existing mock infrastructure.

Implementation Steps

Stage 1: Implement Missing CLI Enhancement Features

1.1 Add JSON Output Support to ralph_loop.sh

Modify the execute_claude_code() function to support structured JSON output format:

• Add new configuration variable OUTPUT_FORMAT="text" (default) in the configuration section (around line 14)
• Add --output-format flag parser in the CLI argument parsing section (around line 631)
• Modify execute_claude_code() to pass format flag to Claude Code CLI: $CLAUDE_CODE_CMD --output-format=$OUTPUT_FORMAT < "$PROMPT_FILE"
• Update analyze_response() calls to handle JSON parsing when OUTPUT_FORMAT="json"
• Create helper function parse_json_response() to extract fields from JSON output
• Validate JSON output format before processing to prevent parsing errors

1.2 Implement Session Continuity

Add session management to maintain context across loops:

• Add SESSION_ID="" variable in configuration section
• Add SESSION_FILE=".ralph_session" to track current session
• Create init_session() function to load or create session ID
• Modify execute_claude_code() to pass --session-id=$SESSION_ID flag to Claude Code
• Extract sessionId from JSON responses and persist to SESSION_FILE
• Add --continue flag to resume previous session
• Implement session validation to ensure session IDs are properly formatted

1.3 Add Allowed Tools Configuration

Implement tool permission management:

• Add ALLOWED_TOOLS="" variable in configuration section
• Add --allowedTools flag parser accepting comma-separated tool list
• Create validate_tools() function to check tool names against whitelist
• Pass --allowed-tools=$ALLOWED_TOOLS to Claude Code CLI
• Add tool permission enforcement in response analysis
• Log tool permission violations for debugging

1.4 Update Help Documentation

Modify show_help() function to document new flags:

• Add --output-format [text|json] description with format details
• Add --continue flag description for session resumption
• Add --allowedTools TOOLS description with examples
• Update examples section with new flag combinations
• Document JSON output schema and session file format

Stage 2: Create Comprehensive Test Suite

2.1 Create Test File Structure

Create tests/unit/test_cli_options.bats with standard BATS structure:

• Add BATS shebang and load test helpers
• Implement setup() function for test initialization
• Implement teardown() function for cleanup
• Source necessary functions from ralph_loop.sh for isolated testing
• Initialize temporary directories for session and configuration files

2.2 JSON Output Tests (3 tests)

Test JSON output parsing functionality:

Test 1: JSON output flag sets OUTPUT_FORMAT variable

• Mock CLI argument parsing with --output-format json
• Assert OUTPUT_FORMAT equals "json"
• Verify flag is properly recognized in argument parser

Test 2: Parse valid JSON response extracts sessionId

• Create fixture JSON response with sessionId field
• Call parse_json_response() function
• Assert extracted sessionId matches expected value
• Verify no data loss during parsing

Test 3: Handle malformed JSON gracefully

• Create fixture with invalid JSON syntax
• Call parse_json_response() with error handling
• Assert function returns error code and logs warning
• Verify graceful degradation without crashing

2.3 Session Continuity Tests (3 tests)

Test session management across loops:

Test 4: init_session creates new session when none exists

• Remove .ralph_session file
• Call init_session()
• Assert new session ID generated and saved to file
• Verify session ID format is valid

Test 5: init_session loads existing session

• Create .ralph_session with known session ID
• Call init_session()
• Assert loaded session ID matches file content
• Verify no session ID regeneration on load

Test 6: --continue flag resumes previous session

• Create .ralph_session with session ID "test-session-123"
• Parse arguments with --continue flag
• Assert SESSION_ID variable equals "test-session-123"
• Verify session persistence across invocations

2.4 Allowed Tools Tests (3 tests)

Test tool permission configuration:

Test 7: --allowedTools flag parses comma-separated list

• Parse arguments with --allowedTools "read_file,write_file,bash"
• Assert ALLOWED_TOOLS contains all three tools
• Verify whitespace handling in tool list

Test 8: validate_tools accepts whitelisted tools

• Set ALLOWED_TOOLS="read_file,write_file"
• Call validate_tools("read_file")
• Assert function returns success (exit code 0)
• Verify tool validation logic

Test 9: validate_tools rejects non-whitelisted tools

• Set ALLOWED_TOOLS="read_file,write_file"
• Call validate_tools("execute_code")
• Assert function returns failure (exit code 1)
• Verify rejection of unauthorized tools

2.5 Flag Behavior Tests (4 tests)

Test CLI flag parsing and interactions:

Test 10: --output-format accepts valid values (text, json)

• Parse arguments with --output-format text and --output-format json
• Assert both are accepted without errors
• Verify format validation

Test 11: --output-format rejects invalid values

• Parse arguments with --output-format xml
• Assert error message displayed and script exits
• Verify error handling for invalid formats

Test 12: Multiple flags combined work correctly

• Parse arguments: --output-format json --continue --allowedTools "read_file"
• Assert all three variables set correctly
• Verify flag interaction and precedence

Test 13: Flag order independence

• Parse arguments in different orders: --continue --output-format json vs --output-format json --continue
• Assert both produce identical configuration
• Verify argument parser robustness

2.6 Error Handling Tests (3 tests)

Test error scenarios with structured responses:

Test 14: JSON error response parsed correctly

• Create fixture JSON with error field: {"error": "API limit reached", "code": 429}
• Call error detection logic
• Assert error extracted and logged appropriately
• Verify error code extraction

Test 15: Missing required JSON fields handled gracefully

• Create JSON response missing sessionId field
• Call parse_json_response()
• Assert function continues without crashing, uses default values
• Verify fallback behavior

Test 16: Empty JSON response handled

• Create fixture with empty JSON object {}
• Call parsing functions
• Assert no crashes, appropriate warnings logged
• Verify empty response handling

2.7 Backward Compatibility Tests (4 tests)

Test compatibility with existing text output:

Test 17: Default output format is text

• Initialize configuration without --output-format flag
• Assert OUTPUT_FORMAT equals "text"
• Verify default behavior preservation

Test 18: Text output parsing still works

• Create fixture with traditional text output
• Call analyze_response() with text format
• Assert analysis completes successfully
• Verify legacy output format support

Test 19: Existing flags unaffected by new features

• Parse arguments: --calls 50 --prompt test.md --verbose
• Assert existing variables (MAX_CALLS_PER_HOUR, PROMPT_FILE, VERBOSE_PROGRESS) set correctly
• Verify no regression in existing functionality

Test 20: Session file optional for backward compatibility

• Remove .ralph_session file
• Run loop without --continue flag
• Assert loop executes normally without session management
• Verify optional session feature

Stage 3: Integration and Validation

3.1 Update Test Helpers

Extend test helper files with new fixtures:

• Create create_sample_json_response() - Generate valid JSON Claude output
• Create create_sample_json_error() - Generate JSON error responses
• Create create_sample_session_file() - Generate session persistence files
• Add helper functions for temporary directory management

3.2 Update CI/CD Pipeline

Ensure GitHub Actions workflow runs new tests:

• Verify BATS discovers test_cli_options.bats automatically
• Add test count validation (should be 75 + 20 = 95 tests)
• Ensure all tests pass before merge
• Add test coverage reporting for new tests

3.3 Documentation Updates

Update project documentation:

• Add new CLI flags to README.md usage section
• Document JSON output schema in CLAUDE.md
• Update IMPLEMENTATION_STATUS.md to mark Phase 4.1 complete
• Create examples showing JSON output and session continuity usage
• Document session file format and structure

Test Execution Flow

Stage 1: Implement CLI Enhancements
  ├─ Add --output-format flag with validation
  ├─ Add --continue flag with session loading
  ├─ Add --allowedTools flag with parsing
  ├─ Implement JSON parsing with error handling
  └─ Implement session management with persistence

Stage 2: Create Test Suite (20 tests)
  ├─ JSON Output Tests (3)
  │  ├─ Test 1: Flag sets OUTPUT_FORMAT
  │  ├─ Test 2: Parse valid JSON response
  │  └─ Test 3: Handle malformed JSON
  ├─ Session Continuity Tests (3)
  │  ├─ Test 4: Create new session
  │  ├─ Test 5: Load existing session
  │  └─ Test 6: Resume with --continue
  ├─ Allowed Tools Tests (3)
  │  ├─ Test 7: Parse tool list
  │  ├─ Test 8: Accept whitelisted tools
  │  └─ Test 9: Reject unauthorized tools
  ├─ Flag Behavior Tests (4)
  │  ├─ Test 10: Accept valid formats
  │  ├─ Test 11: Reject invalid formats
  │  ├─ Test 12: Multiple flags combined
  │  └─ Test 13: Flag order independence
  ├─ Error Handling Tests (3)
  │  ├─ Test 14: Parse JSON errors
  │  ├─ Test 15: Handle missing fields
  │  └─ Test 16: Handle empty responses
  └─ Backward Compatibility Tests (4)
     ├─ Test 17: Default text format
     ├─ Test 18: Text output parsing
     ├─ Test 19: Existing flags work
     └─ Test 20: Optional session file

Stage 3: Integration & Validation
  ├─ Update test helpers with new fixtures
  ├─ Update CI/CD pipeline configuration
  └─ Update documentation

Acceptance Criteria Mapping

Criterion	Implementation Step	Validation
All CLI enhancement features tested	Stages 2.2-2.7	20 tests covering all features
JSON parsing tests pass	Stage 2.2	Tests 1-3 validate JSON handling
Session continuity verified	Stage 2.3	Tests 4-6 validate session management
Tool permissions validated	Stage 2.4	Tests 7-9 validate tool configuration
Backward compatibility confirmed	Stage 2.7	Tests 17-20 ensure existing functionality intact
All tests pass in CI/CD	Stage 3.2	GitHub Actions workflow validates 95 tests

Dependencies and Prerequisites

Critical Dependency: Phase 1 CLI enhancements (issues #28-31) must be implemented first. This plan assumes Stage 1 implementation is completed before Stage 2 test creation.

Required Tools:

• BATS testing framework (already installed per package.json)
• jq for JSON parsing (required for JSON output tests)
• Existing test infrastructure

Existing Resources:

• Test patterns from existing BATS test files
• Mock infrastructure in test helpers
• Fixture generators in test helpers

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a mature BATS testing infrastructure with 75 passing tests covering rate limiting, exit detection, loop execution, and edge cases. The existing CLI in `ralph_loop.sh` supports flags like `--help`, `--calls`, `--prompt`, `--status`, `--monitor`, `--verbose`, `--timeout`, `--reset-circuit`, and `--circuit-status`. However, the modern CLI enhancements mentioned in issue #39 (JSON output, sessionId extraction, session continuity, allowed tools configuration, `--continue`, `--output-format`, `--allowedTools` flags) are **not yet implemented** in the codebase. The test helpers provide robust utilities for creating test fixtures and mocking system commands.

## Approach

Since the Phase 1 CLI enhancements (issues #28-31) are not yet implemented, the implementation plan must address this critical dependency first. The approach follows a two-stage strategy: **Stage 1** implements the missing CLI enhancement features in `ralph_loop.sh`, and **Stage 2** creates comprehensive BATS tests in `tests/unit/test_cli_options.bats` to validate these features. This ensures tests are written against actual implementations rather than hypothetical functionality, following TDD principles where implementation precedes or accompanies test creation. The plan leverages existing test patterns and existing mock infrastructure.

## Implementation Steps

### Stage 1: Implement Missing CLI Enhancement Features

#### 1.1 Add JSON Output Support to ralph_loop.sh

Modify the `execute_claude_code()` function to support structured JSON output format:

- Add new configuration variable `OUTPUT_FORMAT="text"` (default) in the configuration section (around line 14)
- Add `--output-format` flag parser in the CLI argument parsing section (around line 631)
- Modify `execute_claude_code()` to pass format flag to Claude Code CLI: `$CLAUDE_CODE_CMD --output-format=$OUTPUT_FORMAT < "$PROMPT_FILE"`
- Update `analyze_response()` calls to handle JSON parsing when `OUTPUT_FORMAT="json"`
- Create helper function `parse_json_response()` to extract fields from JSON output
- Validate JSON output format before processing to prevent parsing errors

#### 1.2 Implement Session Continuity

Add session management to maintain context across loops:

- Add `SESSION_ID=""` variable in configuration section
- Add `SESSION_FILE=".ralph_session"` to track current session
- Create `init_session()` function to load or create session ID
- Modify `execute_claude_code()` to pass `--session-id=$SESSION_ID` flag to Claude Code
- Extract `sessionId` from JSON responses and persist to `SESSION_FILE`
- Add `--continue` flag to resume previous session
- Implement session validation to ensure session IDs are properly formatted

#### 1.3 Add Allowed Tools Configuration

Implement tool permission management:

- Add `ALLOWED_TOOLS=""` variable in configuration section
- Add `--allowedTools` flag parser accepting comma-separated tool list
- Create `validate_tools()` function to check tool names against whitelist
- Pass `--allowed-tools=$ALLOWED_TOOLS` to Claude Code CLI
- Add tool permission enforcement in response analysis
- Log tool permission violations for debugging

#### 1.4 Update Help Documentation

Modify `show_help()` function to document new flags:

- Add `--output-format [text|json]` description with format details
- Add `--continue` flag description for session resumption
- Add `--allowedTools TOOLS` description with examples
- Update examples section with new flag combinations
- Document JSON output schema and session file format

### Stage 2: Create Comprehensive Test Suite

#### 2.1 Create Test File Structure

Create `tests/unit/test_cli_options.bats` with standard BATS structure:

- Add BATS shebang and load test helpers
- Implement `setup()` function for test initialization
- Implement `teardown()` function for cleanup
- Source necessary functions from `ralph_loop.sh` for isolated testing
- Initialize temporary directories for session and configuration files

#### 2.2 JSON Output Tests (3 tests)

Test JSON output parsing functionality:

**Test 1: JSON output flag sets OUTPUT_FORMAT variable**
- Mock CLI argument parsing with `--output-format json`
- Assert `OUTPUT_FORMAT` equals "json"
- Verify flag is properly recognized in argument parser

**Test 2: Parse valid JSON response extracts sessionId**
- Create fixture JSON response with `sessionId` field
- Call `parse_json_response()` function
- Assert extracted sessionId matches expected value
- Verify no data loss during parsing

**Test 3: Handle malformed JSON gracefully**
- Create fixture with invalid JSON syntax
- Call `parse_json_response()` with error handling
- Assert function returns error code and logs warning
- Verify graceful degradation without crashing

#### 2.3 Session Continuity Tests (3 tests)

Test session management across loops:

**Test 4: init_session creates new session when none exists**
- Remove `.ralph_session` file
- Call `init_session()`
- Assert new session ID generated and saved to file
- Verify session ID format is valid

**Test 5: init_session loads existing session**
- Create `.ralph_session` with known session ID
- Call `init_session()`
- Assert loaded session ID matches file content
- Verify no session ID regeneration on load

**Test 6: --continue flag resumes previous session**
- Create `.ralph_session` with session ID "test-session-123"
- Parse arguments with `--continue` flag
- Assert `SESSION_ID` variable equals "test-session-123"
- Verify session persistence across invocations

#### 2.4 Allowed Tools Tests (3 tests)

Test tool permission configuration:

**Test 7: --allowedTools flag parses comma-separated list**
- Parse arguments with `--allowedTools "read_file,write_file,bash"`
- Assert `ALLOWED_TOOLS` contains all three tools
- Verify whitespace handling in tool list

**Test 8: validate_tools accepts whitelisted tools**
- Set `ALLOWED_TOOLS="read_file,write_file"`
- Call `validate_tools("read_file")`
- Assert function returns success (exit code 0)
- Verify tool validation logic

**Test 9: validate_tools rejects non-whitelisted tools**
- Set `ALLOWED_TOOLS="read_file,write_file"`
- Call `validate_tools("execute_code")`
- Assert function returns failure (exit code 1)
- Verify rejection of unauthorized tools

#### 2.5 Flag Behavior Tests (4 tests)

Test CLI flag parsing and interactions:

**Test 10: --output-format accepts valid values (text, json)**
- Parse arguments with `--output-format text` and `--output-format json`
- Assert both are accepted without errors
- Verify format validation

**Test 11: --output-format rejects invalid values**
- Parse arguments with `--output-format xml`
- Assert error message displayed and script exits
- Verify error handling for invalid formats

**Test 12: Multiple flags combined work correctly**
- Parse arguments: `--output-format json --continue --allowedTools "read_file"`
- Assert all three variables set correctly
- Verify flag interaction and precedence

**Test 13: Flag order independence**
- Parse arguments in different orders: `--continue --output-format json` vs `--output-format json --continue`
- Assert both produce identical configuration
- Verify argument parser robustness

#### 2.6 Error Handling Tests (3 tests)

Test error scenarios with structured responses:

**Test 14: JSON error response parsed correctly**
- Create fixture JSON with error field: `{"error": "API limit reached", "code": 429}`
- Call error detection logic
- Assert error extracted and logged appropriately
- Verify error code extraction

**Test 15: Missing required JSON fields handled gracefully**
- Create JSON response missing `sessionId` field
- Call `parse_json_response()`
- Assert function continues without crashing, uses default values
- Verify fallback behavior

**Test 16: Empty JSON response handled**
- Create fixture with empty JSON object `{}`
- Call parsing functions
- Assert no crashes, appropriate warnings logged
- Verify empty response handling

#### 2.7 Backward Compatibility Tests (4 tests)

Test compatibility with existing text output:

**Test 17: Default output format is text**
- Initialize configuration without `--output-format` flag
- Assert `OUTPUT_FORMAT` equals "text"
- Verify default behavior preservation

**Test 18: Text output parsing still works**
- Create fixture with traditional text output
- Call `analyze_response()` with text format
- Assert analysis completes successfully
- Verify legacy output format support

**Test 19: Existing flags unaffected by new features**
- Parse arguments: `--calls 50 --prompt test.md --verbose`
- Assert existing variables (`MAX_CALLS_PER_HOUR`, `PROMPT_FILE`, `VERBOSE_PROGRESS`) set correctly
- Verify no regression in existing functionality

**Test 20: Session file optional for backward compatibility**
- Remove `.ralph_session` file
- Run loop without `--continue` flag
- Assert loop executes normally without session management
- Verify optional session feature

### Stage 3: Integration and Validation

#### 3.1 Update Test Helpers

Extend test helper files with new fixtures:

- Create `create_sample_json_response()` - Generate valid JSON Claude output
- Create `create_sample_json_error()` - Generate JSON error responses
- Create `create_sample_session_file()` - Generate session persistence files
- Add helper functions for temporary directory management

#### 3.2 Update CI/CD Pipeline

Ensure GitHub Actions workflow runs new tests:

- Verify BATS discovers `test_cli_options.bats` automatically
- Add test count validation (should be 75 + 20 = 95 tests)
- Ensure all tests pass before merge
- Add test coverage reporting for new tests

#### 3.3 Documentation Updates

Update project documentation:

- Add new CLI flags to `README.md` usage section
- Document JSON output schema in `CLAUDE.md`
- Update `IMPLEMENTATION_STATUS.md` to mark Phase 4.1 complete
- Create examples showing JSON output and session continuity usage
- Document session file format and structure

## Test Execution Flow

```
Stage 1: Implement CLI Enhancements
  ├─ Add --output-format flag with validation
  ├─ Add --continue flag with session loading
  ├─ Add --allowedTools flag with parsing
  ├─ Implement JSON parsing with error handling
  └─ Implement session management with persistence

Stage 2: Create Test Suite (20 tests)
  ├─ JSON Output Tests (3)
  │  ├─ Test 1: Flag sets OUTPUT_FORMAT
  │  ├─ Test 2: Parse valid JSON response
  │  └─ Test 3: Handle malformed JSON
  ├─ Session Continuity Tests (3)
  │  ├─ Test 4: Create new session
  │  ├─ Test 5: Load existing session
  │  └─ Test 6: Resume with --continue
  ├─ Allowed Tools Tests (3)
  │  ├─ Test 7: Parse tool list
  │  ├─ Test 8: Accept whitelisted tools
  │  └─ Test 9: Reject unauthorized tools
  ├─ Flag Behavior Tests (4)
  │  ├─ Test 10: Accept valid formats
  │  ├─ Test 11: Reject invalid formats
  │  ├─ Test 12: Multiple flags combined
  │  └─ Test 13: Flag order independence
  ├─ Error Handling Tests (3)
  │  ├─ Test 14: Parse JSON errors
  │  ├─ Test 15: Handle missing fields
  │  └─ Test 16: Handle empty responses
  └─ Backward Compatibility Tests (4)
     ├─ Test 17: Default text format
     ├─ Test 18: Text output parsing
     ├─ Test 19: Existing flags work
     └─ Test 20: Optional session file

Stage 3: Integration & Validation
  ├─ Update test helpers with new fixtures
  ├─ Update CI/CD pipeline configuration
  └─ Update documentation
```

## Acceptance Criteria Mapping

| Criterion | Implementation Step | Validation |
|-----------|-------------------|------------|
| All CLI enhancement features tested | Stages 2.2-2.7 | 20 tests covering all features |
| JSON parsing tests pass | Stage 2.2 | Tests 1-3 validate JSON handling |
| Session continuity verified | Stage 2.3 | Tests 4-6 validate session management |
| Tool permissions validated | Stage 2.4 | Tests 7-9 validate tool configuration |
| Backward compatibility confirmed | Stage 2.7 | Tests 17-20 ensure existing functionality intact |
| All tests pass in CI/CD | Stage 3.2 | GitHub Actions workflow validates 95 tests |

## Dependencies and Prerequisites

**Critical Dependency**: Phase 1 CLI enhancements (issues #28-31) must be implemented first. This plan assumes Stage 1 implementation is completed before Stage 2 test creation.

**Required Tools**:
- BATS testing framework (already installed per package.json)
- jq for JSON parsing (required for JSON output tests)
- Existing test infrastructure

**Existing Resources**:
- Test patterns from existing BATS test files
- Mock infrastructure in test helpers
- Fixture generators in test helpers

---

Execution Information

Branch: main
Commit: 870181b