response_analyzer.sh

#!/bin/bash
# Response Analyzer Component for Ralph
# Analyzes Claude Code output to detect completion signals, test-only loops, and progress

# Source date utilities for cross-platform compatibility
source "$(dirname "${BASH_SOURCE[0]}")/date_utils.sh"

# Response Analysis Functions
# Based on expert recommendations from Martin Fowler, Michael Nygard, Sam Newman

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m'

# Use RALPH_DIR if set by main script, otherwise default to .ralph
RALPH_DIR="${RALPH_DIR:-.ralph}"

# Analysis configuration
COMPLETION_KEYWORDS=("done" "complete" "finished" "all tasks complete" "project complete" "ready for review")
TEST_ONLY_PATTERNS=("npm test" "bats" "pytest" "jest" "cargo test" "go test" "running tests")
NO_WORK_PATTERNS=("nothing to do" "no changes" "already implemented" "up to date")
QUESTION_PATTERNS=("should I" "would you" "do you want" "which approach" "which option" "how should" "what should" "shall I" "do you prefer" "can you clarify" "could you" "what do you think" "please confirm" "need clarification" "awaiting.*input" "waiting.*response" "your preference")

# Detect if Claude is asking questions instead of acting autonomously
# Args: $1 = text content to analyze
# Returns: 0 if questions detected, 1 otherwise
# Outputs: question count on stdout
detect_questions() {
    local content="$1"
    local question_count=0

    if [[ -z "$content" ]]; then
        echo "0"
        return 1
    fi

    # Count lines matching question patterns (case-insensitive)
    for pattern in "${QUESTION_PATTERNS[@]}"; do
        local matches
        matches=$(echo "$content" | grep -ciw "$pattern" 2>/dev/null || echo "0")
        matches=$(echo "$matches" | tr -d '[:space:]')
        matches=${matches:-0}
        question_count=$((question_count + matches))
    done

    echo "$question_count"
    [[ $question_count -gt 0 ]] && return 0 || return 1
}

# =============================================================================
# JSON OUTPUT FORMAT DETECTION AND PARSING
# =============================================================================

# Detect output format (json or text)
# Returns: "json" if valid JSON, "text" otherwise
detect_output_format() {
    local output_file=$1

    if [[ ! -f "$output_file" ]] || [[ ! -s "$output_file" ]]; then
        echo "text"
        return
    fi

    # Check if file starts with { or [ (JSON indicators)
    local first_char=$(head -c 1 "$output_file" 2>/dev/null | tr -d '[:space:]')

    if [[ "$first_char" != "{" && "$first_char" != "[" ]]; then
        echo "text"
        return
    fi

    # Validate as JSON using jq
    if jq empty "$output_file" 2>/dev/null; then
        echo "json"
    else
        echo "text"
    fi
}

# Parse JSON response and extract structured fields
# Creates .ralph/.json_parse_result with normalized analysis data
# Supports THREE JSON formats:
# 1. Flat format: { status, exit_signal, work_type, files_modified, ... }
# 2. Claude CLI object format: { result, sessionId, metadata: { files_changed, has_errors, completion_status, ... } }
# 3. Claude CLI array format: [ {type: "system", ...}, {type: "assistant", ...}, {type: "result", ...} ]
parse_json_response() {
    local output_file=$1
    local result_file="${2:-$RALPH_DIR/.json_parse_result}"
    local normalized_file=""

    if [[ ! -f "$output_file" ]]; then
        echo "ERROR: Output file not found: $output_file" >&2
        return 1
    fi

    # Validate JSON first
    if ! jq empty "$output_file" 2>/dev/null; then
        echo "ERROR: Invalid JSON in output file" >&2
        return 1
    fi

    # Check if JSON is an array (Claude CLI array format)
    # Claude CLI outputs: [{type: "system", ...}, {type: "assistant", ...}, {type: "result", ...}]
    if jq -e 'type == "array"' "$output_file" >/dev/null 2>&1; then
        normalized_file=$(mktemp)

        # Extract the "result" type message from the array (usually the last entry)
        # This contains: result, session_id, is_error, duration_ms, etc.
        local result_obj=$(jq '[.[] | select(.type == "result")] | .[-1] // {}' "$output_file" 2>/dev/null)

        # Guard against empty result_obj if jq fails (review fix: Macroscope)
        [[ -z "$result_obj" ]] && result_obj="{}"

        # Extract session_id from init message as fallback
        local init_session_id=$(jq -r '.[] | select(.type == "system" and .subtype == "init") | .session_id // empty' "$output_file" 2>/dev/null | head -1)

        # Prioritize result object's own session_id, then fall back to init message (review fix: CodeRabbit)
        # This prevents session ID loss when arrays lack an init message with session_id
        local effective_session_id
        effective_session_id=$(echo "$result_obj" | jq -r '.sessionId // .session_id // empty' 2>/dev/null)
        if [[ -z "$effective_session_id" || "$effective_session_id" == "null" ]]; then
            effective_session_id="$init_session_id"
        fi

        # Build normalized object merging result with effective session_id
        if [[ -n "$effective_session_id" && "$effective_session_id" != "null" ]]; then
            echo "$result_obj" | jq --arg sid "$effective_session_id" '. + {sessionId: $sid} | del(.session_id)' > "$normalized_file"
        else
            echo "$result_obj" | jq 'del(.session_id)' > "$normalized_file"
        fi

        # Use normalized file for subsequent parsing
        output_file="$normalized_file"
    fi

    # Detect JSON format by checking for Claude CLI fields
    local has_result_field=$(jq -r 'has("result")' "$output_file" 2>/dev/null)

    # Extract fields - support both flat format and Claude CLI format
    # Priority: Claude CLI fields first, then flat format fields

    # Status: from flat format OR derived from metadata.completion_status
    local status=$(jq -r '.status // "UNKNOWN"' "$output_file" 2>/dev/null)
    local completion_status=$(jq -r '.metadata.completion_status // ""' "$output_file" 2>/dev/null)
    if [[ "$completion_status" == "complete" || "$completion_status" == "COMPLETE" ]]; then
        status="COMPLETE"
    fi

    # Exit signal: from flat format OR derived from completion_status
    # Track whether EXIT_SIGNAL was explicitly provided (vs inferred from STATUS)
    local exit_signal=$(jq -r '.exit_signal // false' "$output_file" 2>/dev/null)
    local explicit_exit_signal_found=$(jq -r 'has("exit_signal")' "$output_file" 2>/dev/null)

    # Bug #1 Fix: If exit_signal is still false, check for RALPH_STATUS block in .result field
    # Claude CLI JSON format embeds the RALPH_STATUS block within the .result text field
    #
    # Supported emit formats (both must be recognized; do not regress to single-format match):
    #   1) Canonical separator-marker format (lib/enable_core.sh:560-568):
    #        ---RALPH_STATUS---
    #        EXIT_SIGNAL: true
    #        ---END_RALPH_STATUS---
    #   2) YAML colon-block format emitted by some agent prompts:
    #        RALPH_STATUS:
    #          EXIT_SIGNAL: true
    #          reason: "..."
    # The downstream EXIT_SIGNAL extraction (grep "EXIT_SIGNAL:" | cut | xargs) handles
    # both layouts uniformly because both emit one EXIT_SIGNAL: <bool> line.
    # See also the parallel check at the structured-output text-parsing fallback below.
    if [[ "$exit_signal" == "false" && "$has_result_field" == "true" ]]; then
        local result_text=$(jq -r '.result // ""' "$output_file" 2>/dev/null)
        if [[ -n "$result_text" ]] && echo "$result_text" | grep -qE -- "---RALPH_STATUS---|RALPH_STATUS:"; then
            # Extract EXIT_SIGNAL value from RALPH_STATUS block within result text
            local embedded_exit_sig
            embedded_exit_sig=$(echo "$result_text" | grep "EXIT_SIGNAL:" | cut -d: -f2 | xargs)
            if [[ -n "$embedded_exit_sig" ]]; then
                # Explicit EXIT_SIGNAL found in RALPH_STATUS block
                explicit_exit_signal_found="true"
                if [[ "$embedded_exit_sig" == "true" ]]; then
                    exit_signal="true"
                    [[ "${VERBOSE_PROGRESS:-}" == "true" ]] && echo "DEBUG: Extracted EXIT_SIGNAL=true from .result RALPH_STATUS block" >&2
                else
                    exit_signal="false"
                    [[ "${VERBOSE_PROGRESS:-}" == "true" ]] && echo "DEBUG: Extracted EXIT_SIGNAL=false from .result RALPH_STATUS block (respecting explicit intent)" >&2
                fi
            fi
            # Also check STATUS field as fallback ONLY when EXIT_SIGNAL was not specified
            # This respects explicit EXIT_SIGNAL: false which means "task complete, continue working"
            local embedded_status
            embedded_status=$(echo "$result_text" | grep "STATUS:" | cut -d: -f2 | xargs)
            if [[ "$embedded_status" == "COMPLETE" && "$explicit_exit_signal_found" != "true" ]]; then
                # STATUS: COMPLETE without any EXIT_SIGNAL field implies completion
                exit_signal="true"
                [[ "${VERBOSE_PROGRESS:-}" == "true" ]] && echo "DEBUG: Inferred EXIT_SIGNAL=true from .result STATUS=COMPLETE (no explicit EXIT_SIGNAL found)" >&2
            fi
        fi
    fi

    # Work type: from flat format
    local work_type=$(jq -r '.work_type // "UNKNOWN"' "$output_file" 2>/dev/null)

    # Files modified: from flat format OR from metadata.files_changed
    local files_modified=$(jq -r '.metadata.files_changed // .files_modified // 0' "$output_file" 2>/dev/null)

    # Error count: from flat format OR derived from metadata.has_errors
    # Note: When only has_errors=true is present (without explicit error_count),
    # we set error_count=1 as a minimum. This is defensive programming since
    # the stuck detection threshold is >5 errors, so 1 error won't trigger it.
    # Actual error count may be higher, but precise count isn't critical for our logic.
    local error_count=$(jq -r '.error_count // 0' "$output_file" 2>/dev/null)
    local has_errors=$(jq -r '.metadata.has_errors // false' "$output_file" 2>/dev/null)
    if [[ "$has_errors" == "true" && "$error_count" == "0" ]]; then
        error_count=1  # At least one error if has_errors is true
    fi

    # Summary: from flat format OR from result field (Claude CLI format)
    local summary=$(jq -r '.result // .summary // ""' "$output_file" 2>/dev/null)

    # Session ID: from Claude CLI format (sessionId) OR from metadata.session_id
    local session_id=$(jq -r '.sessionId // .metadata.session_id // ""' "$output_file" 2>/dev/null)

    # Loop number: from metadata
    local loop_number=$(jq -r '.metadata.loop_number // .loop_number // 0' "$output_file" 2>/dev/null)

    # Confidence: from flat format
    local confidence=$(jq -r '.confidence // 0' "$output_file" 2>/dev/null)

    # Progress indicators: from Claude CLI metadata (optional)
    local progress_count=$(jq -r '.metadata.progress_indicators | if . then length else 0 end' "$output_file" 2>/dev/null)

    # Permission denials: from Claude Code output (Issue #101)
    # When Claude Code is denied permission to run commands, it outputs a permission_denials array
    local permission_denial_count=$(jq -r '.permission_denials | if . then length else 0 end' "$output_file" 2>/dev/null)
    permission_denial_count=$((permission_denial_count + 0))  # Ensure integer

    local has_permission_denials="false"
    if [[ $permission_denial_count -gt 0 ]]; then
        has_permission_denials="true"
    fi

    # Extract denied tool names and commands for logging/display
    # Shows tool_name for non-Bash tools, and for Bash tools shows the command that was denied
    # This handles both cases: AskUserQuestion denial shows "AskUserQuestion",
    # while Bash denial shows "Bash(git commit -m ...)" with truncated command
    local denied_commands_json="[]"
    if [[ $permission_denial_count -gt 0 ]]; then
        denied_commands_json=$(jq -r '[.permission_denials[] | if .tool_name == "Bash" then "Bash(\(.tool_input.command // "?" | split("\n")[0] | .[0:60]))" else .tool_name // "unknown" end]' "$output_file" 2>/dev/null || echo "[]")
    fi

    # Normalize values
    # Convert exit_signal to boolean string
    # Only infer from status/completion_status if no explicit EXIT_SIGNAL was provided
    if [[ "$explicit_exit_signal_found" == "true" ]]; then
        # Respect explicit EXIT_SIGNAL value (already set above)
        [[ "$exit_signal" == "true" ]] && exit_signal="true" || exit_signal="false"
    elif [[ "$exit_signal" == "true" || "$status" == "COMPLETE" || "$completion_status" == "complete" || "$completion_status" == "COMPLETE" ]]; then
        exit_signal="true"
    else
        exit_signal="false"
    fi

    # Determine is_test_only from work_type
    local is_test_only="false"
    if [[ "$work_type" == "TEST_ONLY" ]]; then
        is_test_only="true"
    fi

    # Determine is_stuck from error_count (threshold >5)
    local is_stuck="false"
    error_count=$((error_count + 0))  # Ensure integer
    if [[ $error_count -gt 5 ]]; then
        is_stuck="true"
    fi

    # Ensure files_modified is integer
    files_modified=$((files_modified + 0))

    # Ensure progress_count is integer
    progress_count=$((progress_count + 0))

    # Calculate has_completion_signal
    local has_completion_signal="false"
    if [[ "$status" == "COMPLETE" || "$exit_signal" == "true" ]]; then
        has_completion_signal="true"
    fi

    # Boost confidence based on structured data availability
    if [[ "$has_result_field" == "true" ]]; then
        confidence=$((confidence + 20))  # Structured response boost
    fi
    if [[ $progress_count -gt 0 ]]; then
        confidence=$((confidence + progress_count * 5))  # Progress indicators boost
    fi

    # Write normalized result using jq for safe JSON construction
    # String fields use --arg (auto-escapes), numeric/boolean use --argjson
    jq -n \
        --arg status "$status" \
        --argjson exit_signal "$exit_signal" \
        --argjson is_test_only "$is_test_only" \
        --argjson is_stuck "$is_stuck" \
        --argjson has_completion_signal "$has_completion_signal" \
        --argjson files_modified "$files_modified" \
        --argjson error_count "$error_count" \
        --arg summary "$summary" \
        --argjson loop_number "$loop_number" \
        --arg session_id "$session_id" \
        --argjson confidence "$confidence" \
        --argjson has_permission_denials "$has_permission_denials" \
        --argjson permission_denial_count "$permission_denial_count" \
        --argjson denied_commands "$denied_commands_json" \
        '{
            status: $status,
            exit_signal: $exit_signal,
            is_test_only: $is_test_only,
            is_stuck: $is_stuck,
            has_completion_signal: $has_completion_signal,
            files_modified: $files_modified,
            error_count: $error_count,
            summary: $summary,
            loop_number: $loop_number,
            session_id: $session_id,
            confidence: $confidence,
            has_permission_denials: $has_permission_denials,
            permission_denial_count: $permission_denial_count,
            denied_commands: $denied_commands,
            metadata: {
                loop_number: $loop_number,
                session_id: $session_id
            }
        }' > "$result_file"

    # Cleanup temporary normalized file if created (for array format handling)
    if [[ -n "$normalized_file" && -f "$normalized_file" ]]; then
        rm -f "$normalized_file"
    fi

    return 0
}

# Analyze Claude Code response and extract signals
analyze_response() {
    local output_file=$1
    local loop_number=$2
    local analysis_result_file=${3:-"$RALPH_DIR/.response_analysis"}

    # Initialize analysis result
    local has_completion_signal=false
    local is_test_only=false
    local is_stuck=false
    local has_progress=false
    local confidence_score=0
    local exit_signal=false
    local work_summary=""
    local files_modified=0

    # Read output file
    if [[ ! -f "$output_file" ]]; then
        echo "ERROR: Output file not found: $output_file"
        return 1
    fi

    local output_content=$(cat "$output_file")
    local output_length=${#output_content}

    # Detect output format and try JSON parsing first
    local output_format=$(detect_output_format "$output_file")

    if [[ "$output_format" == "json" ]]; then
        # Try JSON parsing
        if parse_json_response "$output_file" "$RALPH_DIR/.json_parse_result" 2>/dev/null; then
            # Extract values from JSON parse result
            has_completion_signal=$(jq -r '.has_completion_signal' $RALPH_DIR/.json_parse_result 2>/dev/null || echo "false")
            exit_signal=$(jq -r '.exit_signal' $RALPH_DIR/.json_parse_result 2>/dev/null || echo "false")
            is_test_only=$(jq -r '.is_test_only' $RALPH_DIR/.json_parse_result 2>/dev/null || echo "false")
            is_stuck=$(jq -r '.is_stuck' $RALPH_DIR/.json_parse_result 2>/dev/null || echo "false")
            work_summary=$(jq -r '.summary' $RALPH_DIR/.json_parse_result 2>/dev/null || echo "")
            files_modified=$(jq -r '.files_modified' $RALPH_DIR/.json_parse_result 2>/dev/null || echo "0")
            local json_confidence=$(jq -r '.confidence' $RALPH_DIR/.json_parse_result 2>/dev/null || echo "0")
            local session_id=$(jq -r '.session_id' $RALPH_DIR/.json_parse_result 2>/dev/null || echo "")

            # Extract permission denial fields (Issue #101)
            local has_permission_denials=$(jq -r '.has_permission_denials' $RALPH_DIR/.json_parse_result 2>/dev/null || echo "false")
            local permission_denial_count=$(jq -r '.permission_denial_count' $RALPH_DIR/.json_parse_result 2>/dev/null || echo "0")
            local denied_commands_json=$(jq -r '.denied_commands' $RALPH_DIR/.json_parse_result 2>/dev/null || echo "[]")

            # Persist session ID if present (for session continuity across loop iterations)
            if [[ -n "$session_id" && "$session_id" != "null" ]]; then
                store_session_id "$session_id"
                [[ "${VERBOSE_PROGRESS:-}" == "true" ]] && echo "DEBUG: Persisted session ID: $session_id" >&2
            fi

            # JSON parsing provides high confidence
            if [[ "$exit_signal" == "true" ]]; then
                confidence_score=100
            else
                confidence_score=$((json_confidence + 50))
            fi

            # Detect questions in JSON response text (Issue #190 Bug 2)
            local asking_questions=false
            local question_count=0
            if question_count=$(detect_questions "$work_summary"); then
                asking_questions=true
            fi

            # Check for file changes via git (supplements JSON data)
            # Fix #141: Detect both uncommitted changes AND committed changes
            if command -v git &>/dev/null && git rev-parse --git-dir >/dev/null 2>&1; then
                local git_files=0
                local loop_start_sha=""
                local current_sha=""

                if [[ -f "$RALPH_DIR/.loop_start_sha" ]]; then
                    loop_start_sha=$(cat "$RALPH_DIR/.loop_start_sha" 2>/dev/null || echo "")
                fi
                current_sha=$(git rev-parse HEAD 2>/dev/null || echo "")

                # Check if commits were made (HEAD changed)
                if [[ -n "$loop_start_sha" && -n "$current_sha" && "$loop_start_sha" != "$current_sha" ]]; then
                    # Commits were made - count union of committed files AND working tree changes
                    git_files=$(
                        {
                            git diff --name-only "$loop_start_sha" "$current_sha" 2>/dev/null
                            git diff --name-only HEAD 2>/dev/null           # unstaged changes
                            git diff --name-only --cached 2>/dev/null       # staged changes
                        } | sort -u | wc -l
                    )
                else
                    # No commits - check for uncommitted changes (staged + unstaged)
                    git_files=$(
                        {
                            git diff --name-only 2>/dev/null                # unstaged changes
                            git diff --name-only --cached 2>/dev/null       # staged changes
                        } | sort -u | wc -l
                    )
                fi

                if [[ $git_files -gt 0 ]]; then
                    has_progress=true
                    files_modified=$git_files
                fi
            fi

            # Write analysis results for JSON path using jq for safe construction
            jq -n \
                --argjson loop_number "$loop_number" \
                --arg timestamp "$(get_iso_timestamp)" \
                --arg output_file "$output_file" \
                --arg output_format "json" \
                --argjson has_completion_signal "$has_completion_signal" \
                --argjson is_test_only "$is_test_only" \
                --argjson is_stuck "$is_stuck" \
                --argjson has_progress "$has_progress" \
                --argjson files_modified "$files_modified" \
                --argjson confidence_score "$confidence_score" \
                --argjson exit_signal "$exit_signal" \
                --arg work_summary "$work_summary" \
                --argjson output_length "$output_length" \
                --argjson has_permission_denials "$has_permission_denials" \
                --argjson permission_denial_count "$permission_denial_count" \
                --argjson denied_commands "$denied_commands_json" \
                --argjson asking_questions "$asking_questions" \
                --argjson question_count "$question_count" \
                '{
                    loop_number: $loop_number,
                    timestamp: $timestamp,
                    output_file: $output_file,
                    output_format: $output_format,
                    analysis: {
                        has_completion_signal: $has_completion_signal,
                        is_test_only: $is_test_only,
                        is_stuck: $is_stuck,
                        has_progress: $has_progress,
                        files_modified: $files_modified,
                        confidence_score: $confidence_score,
                        exit_signal: $exit_signal,
                        work_summary: $work_summary,
                        output_length: $output_length,
                        has_permission_denials: $has_permission_denials,
                        permission_denial_count: $permission_denial_count,
                        denied_commands: $denied_commands,
                        asking_questions: $asking_questions,
                        question_count: $question_count
                    }
                }' > "$analysis_result_file"
            rm -f "$RALPH_DIR/.json_parse_result"
            return 0
        fi
        # If JSON parsing failed, fall through to text parsing
    fi

    # Text parsing fallback (original logic)

    # Track whether an explicit EXIT_SIGNAL was found in RALPH_STATUS block
    # If explicit signal found, heuristics should NOT override Claude's intent
    local explicit_exit_signal_found=false

    # 1. Check for explicit structured output (if Claude follows schema)
    # Match both the canonical "---RALPH_STATUS---" separator-marker format AND
    # the YAML colon-block format ("RALPH_STATUS:" with indented keys) some agent
    # prompts emit. The downstream EXIT_SIGNAL/STATUS extraction handles both
    # uniformly because each emits one "EXIT_SIGNAL: <bool>" line.
    # See also the parallel check in the JSON-mode .result text path above.
    if grep -qE -- "---RALPH_STATUS---|RALPH_STATUS:" "$output_file"; then
        # Parse structured output
        local status=$(grep "STATUS:" "$output_file" | cut -d: -f2 | xargs)
        local exit_sig=$(grep "EXIT_SIGNAL:" "$output_file" | cut -d: -f2 | xargs)

        # If EXIT_SIGNAL is explicitly provided, respect it
        if [[ -n "$exit_sig" ]]; then
            explicit_exit_signal_found=true
            if [[ "$exit_sig" == "true" ]]; then
                has_completion_signal=true
                exit_signal=true
                confidence_score=100
            else
                # Explicit EXIT_SIGNAL: false - Claude says to continue
                exit_signal=false
            fi
        elif [[ "$status" == "COMPLETE" ]]; then
            # No explicit EXIT_SIGNAL but STATUS is COMPLETE
            has_completion_signal=true
            exit_signal=true
            confidence_score=100
        fi
    fi

    # 2. Detect completion keywords in natural language output
    for keyword in "${COMPLETION_KEYWORDS[@]}"; do
        if grep -qi "$keyword" "$output_file"; then
            has_completion_signal=true
            ((confidence_score+=10))
            break
        fi
    done

    # 3. Detect test-only loops
    local test_command_count=0
    local implementation_count=0
    local error_count=0

    test_command_count=$(grep -c -i "running tests\|npm test\|bats\|pytest\|jest" "$output_file" 2>/dev/null | head -1 || echo "0")
    implementation_count=$(grep -c -i "implementing\|creating\|writing\|adding\|function\|class" "$output_file" 2>/dev/null | head -1 || echo "0")

    # Strip whitespace and ensure it's a number
    test_command_count=$(echo "$test_command_count" | tr -d '[:space:]')
    implementation_count=$(echo "$implementation_count" | tr -d '[:space:]')

    # Convert to integers with default fallback
    test_command_count=${test_command_count:-0}
    implementation_count=${implementation_count:-0}
    test_command_count=$((test_command_count + 0))
    implementation_count=$((implementation_count + 0))

    if [[ $test_command_count -gt 0 ]] && [[ $implementation_count -eq 0 ]]; then
        is_test_only=true
        work_summary="Test execution only, no implementation"
    fi

    # 4. Detect stuck/error loops
    # Use two-stage filtering to avoid counting JSON field names as errors
    # Stage 1: Filter out JSON field patterns like "is_error": false
    # Stage 2: Count actual error messages in specific contexts
    # Pattern aligned with ralph_loop.sh to ensure consistent behavior
    error_count=$(grep -v '"[^"]*error[^"]*":' "$output_file" 2>/dev/null | \
                  grep -cE '(^Error:|^ERROR:|^error:|\]: error|Link: error|Error occurred|failed with error|[Ee]xception|Fatal|FATAL)' \
                  2>/dev/null || echo "0")
    error_count=$(echo "$error_count" | tr -d '[:space:]')
    error_count=${error_count:-0}
    error_count=$((error_count + 0))

    if [[ $error_count -gt 5 ]]; then
        is_stuck=true
    fi

    # 5. Detect "nothing to do" patterns
    for pattern in "${NO_WORK_PATTERNS[@]}"; do
        if grep -qi "$pattern" "$output_file"; then
            has_completion_signal=true
            ((confidence_score+=15))
            work_summary="No work remaining"
            break
        fi
    done

    # 5.5. Detect question patterns (Claude asking instead of acting) (Issue #190 Bug 2)
    local asking_questions=false
    local question_count=0
    if question_count=$(detect_questions "$output_content"); then
        asking_questions=true
        work_summary="Claude is asking questions instead of acting autonomously"
    fi

    # 6. Check for file changes (git integration)
    # Fix #141: Detect both uncommitted changes AND committed changes
    if command -v git &>/dev/null && git rev-parse --git-dir >/dev/null 2>&1; then
        local loop_start_sha=""
        local current_sha=""

        if [[ -f "$RALPH_DIR/.loop_start_sha" ]]; then
            loop_start_sha=$(cat "$RALPH_DIR/.loop_start_sha" 2>/dev/null || echo "")
        fi
        current_sha=$(git rev-parse HEAD 2>/dev/null || echo "")

        # Check if commits were made (HEAD changed)
        if [[ -n "$loop_start_sha" && -n "$current_sha" && "$loop_start_sha" != "$current_sha" ]]; then
            # Commits were made - count union of committed files AND working tree changes
            files_modified=$(
                {
                    git diff --name-only "$loop_start_sha" "$current_sha" 2>/dev/null
                    git diff --name-only HEAD 2>/dev/null           # unstaged changes
                    git diff --name-only --cached 2>/dev/null       # staged changes
                } | sort -u | wc -l
            )
        else
            # No commits - check for uncommitted changes (staged + unstaged)
            files_modified=$(
                {
                    git diff --name-only 2>/dev/null                # unstaged changes
                    git diff --name-only --cached 2>/dev/null       # staged changes
                } | sort -u | wc -l
            )
        fi

        if [[ $files_modified -gt 0 ]]; then
            has_progress=true
            ((confidence_score+=20))
        fi
    fi

    # 7. Analyze output length trends (detect declining engagement)
    if [[ -f "$RALPH_DIR/.last_output_length" ]]; then
        local last_length=$(cat "$RALPH_DIR/.last_output_length")
        local length_ratio=$((output_length * 100 / last_length))

        if [[ $length_ratio -lt 50 ]]; then
            # Output is less than 50% of previous - possible completion
            ((confidence_score+=10))
        fi
    fi
    echo "$output_length" > "$RALPH_DIR/.last_output_length"

    # 8. Extract work summary from output
    if [[ -z "$work_summary" ]]; then
        # Try to find summary in output
        work_summary=$(grep -i "summary\|completed\|implemented" "$output_file" | head -1 | cut -c 1-100)
        if [[ -z "$work_summary" ]]; then
            work_summary="Output analyzed, no explicit summary found"
        fi
    fi

    # 9. Determine exit signal based on confidence (heuristic)
    # IMPORTANT: Only apply heuristics if no explicit EXIT_SIGNAL was found in RALPH_STATUS
    # Claude's explicit intent takes precedence over natural language pattern matching
    if [[ "$explicit_exit_signal_found" != "true" ]]; then
        if [[ "$output_format" == "json" ]]; then
            # JSON mode with failed parse: suppress heuristics entirely (Issue #224)
            # A malformed/truncated JSON response is not a completion signal.
            # Only an explicit EXIT_SIGNAL from a RALPH_STATUS block can trigger exit.
            [[ "${VERBOSE_PROGRESS:-}" == "true" ]] && echo "DEBUG: JSON mode, no explicit EXIT_SIGNAL — suppressing heuristic exit (confidence=$confidence_score)" >&2
        elif [[ $confidence_score -ge 70 && "$has_completion_signal" == "true" ]]; then
            # Text mode: require BOTH high confidence AND a structural completion signal (Issue #224)
            # Raised from >=40 OR has_completion_signal to prevent documentation keywords
            # ("setup is done", "implementation complete") from triggering false-positive exits.
            exit_signal=true
        fi
    fi

    # Write analysis results to file (text parsing path) using jq for safe construction
    # Note: Permission denial fields default to false/0 since text output doesn't include this data
    jq -n \
        --argjson loop_number "$loop_number" \
        --arg timestamp "$(get_iso_timestamp)" \
        --arg output_file "$output_file" \
        --arg output_format "text" \
        --argjson has_completion_signal "$has_completion_signal" \
        --argjson is_test_only "$is_test_only" \
        --argjson is_stuck "$is_stuck" \
        --argjson has_progress "$has_progress" \
        --argjson files_modified "$files_modified" \
        --argjson confidence_score "$confidence_score" \
        --argjson exit_signal "$exit_signal" \
        --arg work_summary "$work_summary" \
        --argjson output_length "$output_length" \
        --argjson asking_questions "$asking_questions" \
        --argjson question_count "$question_count" \
        '{
            loop_number: $loop_number,
            timestamp: $timestamp,
            output_file: $output_file,
            output_format: $output_format,
            analysis: {
                has_completion_signal: $has_completion_signal,
                is_test_only: $is_test_only,
                is_stuck: $is_stuck,
                has_progress: $has_progress,
                files_modified: $files_modified,
                confidence_score: $confidence_score,
                exit_signal: $exit_signal,
                work_summary: $work_summary,
                output_length: $output_length,
                has_permission_denials: false,
                permission_denial_count: 0,
                denied_commands: [],
                asking_questions: $asking_questions,
                question_count: $question_count
            }
        }' > "$analysis_result_file"

    # Always return 0 (success) - callers should check the JSON result file
    # Returning non-zero would cause issues with set -e and test frameworks
    return 0
}

# Update exit signals file based on analysis
update_exit_signals() {
    local analysis_file=${1:-"$RALPH_DIR/.response_analysis"}
    local exit_signals_file=${2:-"$RALPH_DIR/.exit_signals"}

    if [[ ! -f "$analysis_file" ]]; then
        echo "ERROR: Analysis file not found: $analysis_file"
        return 1
    fi

    # Read analysis results
    local is_test_only=$(jq -r '.analysis.is_test_only' "$analysis_file")
    local has_completion_signal=$(jq -r '.analysis.has_completion_signal' "$analysis_file")
    local loop_number=$(jq -r '.loop_number' "$analysis_file")
    local has_progress=$(jq -r '.analysis.has_progress' "$analysis_file")

    # Read current exit signals
    local signals=$(cat "$exit_signals_file" 2>/dev/null || echo '{"test_only_loops": [], "done_signals": [], "completion_indicators": []}')

    # Update test_only_loops array
    if [[ "$is_test_only" == "true" ]]; then
        signals=$(echo "$signals" | jq ".test_only_loops += [$loop_number]")
    else
        # Clear test_only_loops if we had implementation
        if [[ "$has_progress" == "true" ]]; then
            signals=$(echo "$signals" | jq '.test_only_loops = []')
        fi
    fi

    # Update done_signals array
    if [[ "$has_completion_signal" == "true" ]]; then
        signals=$(echo "$signals" | jq ".done_signals += [$loop_number]")
    fi

    # Update completion_indicators array (only when Claude explicitly signals exit)
    # Note: Previously used confidence >= 60, but JSON mode always has confidence >= 70
    # due to deterministic scoring (+50 for JSON format, +20 for result field).
    # This caused premature exits after 5 loops. Now we respect Claude's explicit intent.
    local exit_signal=$(jq -r '.analysis.exit_signal // false' "$analysis_file")
    if [[ "$exit_signal" == "true" ]]; then
        signals=$(echo "$signals" | jq ".completion_indicators += [$loop_number]")
    fi

    # Keep only last 5 signals (rolling window)
    signals=$(echo "$signals" | jq '.test_only_loops = .test_only_loops[-5:]')
    signals=$(echo "$signals" | jq '.done_signals = .done_signals[-5:]')
    signals=$(echo "$signals" | jq '.completion_indicators = .completion_indicators[-5:]')

    # Write updated signals
    echo "$signals" > "$exit_signals_file"

    return 0
}

# Log analysis results in human-readable format
log_analysis_summary() {
    local analysis_file=${1:-"$RALPH_DIR/.response_analysis"}

    if [[ ! -f "$analysis_file" ]]; then
        return 1
    fi

    local loop=$(jq -r '.loop_number' "$analysis_file")
    local exit_sig=$(jq -r '.analysis.exit_signal' "$analysis_file")
    local confidence=$(jq -r '.analysis.confidence_score' "$analysis_file")
    local test_only=$(jq -r '.analysis.is_test_only' "$analysis_file")
    local files_changed=$(jq -r '.analysis.files_modified' "$analysis_file")
    local summary=$(jq -r '.analysis.work_summary' "$analysis_file")

    echo -e "${BLUE}╔════════════════════════════════════════════════════════════╗${NC}"
    echo -e "${BLUE}║           Response Analysis - Loop #$loop                 ║${NC}"
    echo -e "${BLUE}╚════════════════════════════════════════════════════════════╝${NC}"
    echo -e "${YELLOW}Exit Signal:${NC}      $exit_sig"
    echo -e "${YELLOW}Confidence:${NC}       $confidence%"
    echo -e "${YELLOW}Test Only:${NC}        $test_only"
    echo -e "${YELLOW}Files Changed:${NC}    $files_changed"
    echo -e "${YELLOW}Summary:${NC}          $summary"
    echo ""
}

# Detect if Claude is stuck (repeating same errors)
detect_stuck_loop() {
    local current_output=$1
    local history_dir=${2:-"$RALPH_DIR/logs"}

    # Get last 3 output files
    local recent_outputs=$(ls -t "$history_dir"/claude_output_*.log 2>/dev/null | head -3)

    if [[ -z "$recent_outputs" ]]; then
        return 1  # Not enough history
    fi

    # Extract key errors from current output using two-stage filtering
    # Stage 1: Filter out JSON field patterns to avoid false positives
    # Stage 2: Extract actual error messages
    local current_errors=$(grep -v '"[^"]*error[^"]*":' "$current_output" 2>/dev/null | \
                          grep -E '(^Error:|^ERROR:|^error:|\]: error|Link: error|Error occurred|failed with error|[Ee]xception|Fatal|FATAL)' 2>/dev/null | \
                          sort | uniq)

    if [[ -z "$current_errors" ]]; then
        return 1  # No errors
    fi

    # Check if same errors appear in all recent outputs
    # For multi-line errors, verify ALL error lines appear in ALL history files
    local all_files_match=true
    while IFS= read -r output_file; do
        local file_matches_all=true
        while IFS= read -r error_line; do
            # Use -F for literal fixed-string matching (not regex)
            if ! grep -qF "$error_line" "$output_file" 2>/dev/null; then
                file_matches_all=false
                break
            fi
        done <<< "$current_errors"

        if [[ "$file_matches_all" != "true" ]]; then
            all_files_match=false
            break
        fi
    done <<< "$recent_outputs"

    if [[ "$all_files_match" == "true" ]]; then
        return 0  # Stuck on same error(s)
    else
        return 1  # Making progress or different errors
    fi
}

# =============================================================================
# SESSION MANAGEMENT FUNCTIONS
# =============================================================================

# Session file location - standardized across ralph_loop.sh and response_analyzer.sh
SESSION_FILE="$RALPH_DIR/.claude_session_id"
# Session expiration time in seconds (24 hours)
SESSION_EXPIRATION_SECONDS=86400

# Store session ID to file with timestamp
# Usage: store_session_id "session-uuid-123"
store_session_id() {
    local session_id=$1

    if [[ -z "$session_id" ]]; then
        return 1
    fi

    # Write session with timestamp using jq for safe JSON construction
    jq -n \
        --arg session_id "$session_id" \
        --arg timestamp "$(get_iso_timestamp)" \
        '{
            session_id: $session_id,
            timestamp: $timestamp
        }' > "$SESSION_FILE"

    return 0
}

# Get the last stored session ID
# Returns: session ID string or empty if not found
get_last_session_id() {
    if [[ ! -f "$SESSION_FILE" ]]; then
        echo ""
        return 0
    fi

    # Extract session_id from JSON file
    local session_id=$(jq -r '.session_id // ""' "$SESSION_FILE" 2>/dev/null)
    echo "$session_id"
    return 0
}

# Check if the stored session should be resumed
# Returns: 0 (true) if session is valid and recent, 1 (false) otherwise
should_resume_session() {
    if [[ ! -f "$SESSION_FILE" ]]; then
        echo "false"
        return 1
    fi

    # Get session timestamp
    local timestamp=$(jq -r '.timestamp // ""' "$SESSION_FILE" 2>/dev/null)

    if [[ -z "$timestamp" ]]; then
        echo "false"
        return 1
    fi

    # Calculate session age using date utilities
    local now=$(get_epoch_seconds)
    local session_time

    # Parse ISO timestamp to epoch - try multiple formats for cross-platform compatibility
    # Strip milliseconds if present (e.g., 2026-01-09T10:30:00.123+00:00 → 2026-01-09T10:30:00+00:00)
    local clean_timestamp="${timestamp}"
    if [[ "$timestamp" =~ \.[0-9]+[+-Z] ]]; then
        clean_timestamp=$(echo "$timestamp" | sed 's/\.[0-9]*\([+-Z]\)/\1/')
    fi

    if command -v gdate &>/dev/null; then
        # macOS with coreutils
        session_time=$(gdate -d "$clean_timestamp" +%s 2>/dev/null)
    elif date --version 2>&1 | grep -q GNU; then
        # GNU date (Linux)
        session_time=$(date -d "$clean_timestamp" +%s 2>/dev/null)
    else
        # BSD date (macOS without coreutils) - try parsing ISO format
        # Format: 2026-01-09T10:30:00+00:00 or 2026-01-09T10:30:00Z
        # Strip timezone suffix for BSD date parsing
        local date_only="${clean_timestamp%[+-Z]*}"
        session_time=$(date -j -f "%Y-%m-%dT%H:%M:%S" "$date_only" +%s 2>/dev/null)
    fi

    # If we couldn't parse the timestamp, consider session expired
    if [[ -z "$session_time" || ! "$session_time" =~ ^[0-9]+$ ]]; then
        echo "false"
        return 1
    fi

    # Calculate age in seconds
    local age=$((now - session_time))

    # Check if session is still valid (less than expiration time)
    if [[ $age -lt $SESSION_EXPIRATION_SECONDS ]]; then
        echo "true"
        return 0
    else
        echo "false"
        return 1
    fi
}

# Export functions for use in ralph_loop.sh
export -f detect_output_format
export -f parse_json_response
export -f analyze_response
export -f update_exit_signals
export -f log_analysis_summary
export -f detect_stuck_loop
export -f detect_questions
export -f store_session_id
export -f get_last_session_id
export -f should_resume_session