[Phase 2.5] ReactAgent iteration budget too small for multi-file tasks

[frankbria]

Problem

With a 30-iteration budget, the ReactAgent cannot complete tasks that require creating multiple files. Each file creation + lint-fix cycle takes 3-5 iterations, and the agent spends ~9 iterations on exploration (see #373). This leaves budget for only 4-7 files.

Observed Behavior

Task "Design Data Model for Tasks" on cf-test:

• Iterations 1-9: Reading/exploring (see [Phase 2.5] ReactAgent wastes 30% of iteration budget on redundant file exploration #373)
• Iteration 10-15: Create + lint-fix models.py → PASSED
• Iteration 16-18: Create + lint-fix storage.py → PASSED
• Iteration 21: Edit __init__.py → PASSED
• Iteration 28: Create test_models.py → FAILED (only 2 iterations left to fix)
• Iteration 30: Hit max → FAILED

The agent generated working, lint-clean code for 3 files but ran out of budget before completing the task.

Contributing Factors

1. Exploration waste ([Phase 2.5] ReactAgent wastes 30% of iteration budget on redundant file exploration #373) — 9 iterations reading files the system prompt could include
2. Lint fix overhead — each file requires 2-4 iterations to pass ruff (create → get errors → fix → verify)
3. Fixed budget — 30 iterations regardless of task complexity
4. No early termination — agent doesn't signal "I'm done" when the code is ready; it keeps iterating

Proposed Fixes

Several complementary approaches:

1. Fix [Phase 2.5] ReactAgent wastes 30% of iteration budget on redundant file exploration #373 first — reducing exploration from 9 to 2-3 iterations immediately frees 6-7 iterations
2. Adaptive iteration budget — scale budget based on task complexity (number of files expected, dependency count)
3. Ruff auto-fix integration — run ruff check --fix automatically before the lint gate, reducing fix iterations from 3-5 to 1
4. Agent completion signal — let the agent end early when it determines the task is done (stop_reason check)

Impact

After fixing #372 (gate resilience) and #373 (exploration waste), the effective iteration budget would be ~25 iterations for implementation. With ruff auto-fix, each file would take ~2 iterations. This would allow 10-12 files per task — sufficient for most tasks.

Files

• codeframe/core/react_agent.py — _react_loop() iteration limit, _build_system_prompt() for context pre-loading
• codeframe/core/gates.py — potential ruff auto-fix integration

[traycerai]

Plan

Observations

The ReactAgent currently has a fixed 30-iteration budget that proves insufficient for multi-file tasks. Analysis shows: (1) ContextLoader already pre-loads relevant files but agents still spend ~9 iterations exploring, (2) each file creation requires 3-5 iterations for lint-fix cycles, (3) ruff auto-fix infrastructure exists in legacy file:codeframe/core/agent.py but isn't integrated into the ReactAgent's main loop, and (4) no early termination mechanism exists despite LLM responses including stop_reason signals.

Approach

The plan addresses all four contributing factors through complementary improvements: enhance context pre-loading to eliminate exploration waste, implement adaptive iteration budgets based on task complexity, integrate ruff auto-fix into the ReactAgent's tool execution pipeline, and add early termination detection. This multi-pronged approach should increase effective budget from ~21 iterations (30 - 9 exploration) to ~25+ iterations while reducing per-file overhead from 3-5 to 1-2 iterations, enabling 10-12 files per task.

Implementation Steps

1. Enhance Context Pre-Loading (Fix #373)

Objective: Reduce exploration iterations from 9 to 2-3 by improving what's included in the initial system prompt.

File: file:codeframe/core/react_agent.py

Modify _build_system_prompt() method to:

• Include more comprehensive file tree structure in the initial prompt
• Pre-load configuration files (pyproject.toml, package.json, .env.example, AGENTS.md, CLAUDE.md)
• Add explicit instructions about available files to discourage redundant exploration
• Include directory structure with file counts per directory
• Add a "Files Already Loaded" section listing all pre-loaded file paths

File: file:codeframe/core/context.py

Enhance ContextLoader.load() to:

• Automatically include critical configuration files regardless of relevance score
• Increase the number of files shown in repository structure from 100 to 200
• Add a new method _load_critical_files() that always loads: README.md, pyproject.toml, package.json, setup.py, requirements.txt, tsconfig.json
• Adjust relevance scoring to boost configuration and documentation files

2. Implement Adaptive Iteration Budget

Objective: Scale iteration budget based on task complexity indicators.

File: file:codeframe/core/react_agent.py

Add new method _calculate_adaptive_budget():

• Analyze task description for complexity indicators (number of files mentioned, keywords like "multiple", "several", "all")
• Check if task has subtasks or dependencies
• Examine PRD length and complexity
• Calculate budget: base 30 + (estimated_files × 5) + (has_subtasks × 10)
• Cap maximum at 100 iterations to prevent runaway execution

Modify __init__():

• Add parameter adaptive_budget: bool = True
• If enabled, call _calculate_adaptive_budget() to override max_iterations
• Log the calculated budget for observability

File: file:codeframe/core/models.py

Add task metadata fields if not present:

• estimated_complexity: Optional[str] (low/medium/high)
• estimated_file_count: Optional[int]

3. Integrate Ruff Auto-Fix into ReactAgent

Objective: Reduce lint-fix iterations from 3-5 to 1-2 by running auto-fix before lint gate.

File: file:codeframe/core/react_agent.py

Modify _execute_tool_with_lint() method:

• After successful file write/edit operations, automatically run ruff check --fix {file} if file extension is .py or .pyi
• Use the existing ruff infrastructure from file:codeframe/core/gates.py
• Only run the lint gate check after auto-fix completes
• Log auto-fix results for debugging

Add new method _auto_fix_file():

• Accept file path as parameter
• Detect file type and select appropriate auto-fix tool (ruff for Python, eslint --fix for JS/TS)
• Run auto-fix command using subprocess with 30s timeout
• Return boolean indicating success/failure
• Emit event for observability

File: file:codeframe/core/gates.py

Add new function run_autofix_on_file():

• Similar to run_lint_on_file() but runs with --fix flag
• Support ruff, eslint, and other fixable linters
• Return GateCheck with details of what was fixed
• Update LINTER_REGISTRY to include auto-fix commands

4. Add Early Termination via Stop Reason Detection

Objective: Allow agent to signal completion before hitting max_iterations.

File: file:codeframe/core/react_agent.py

Modify _react_loop() method:

• Check LLM response for stop_reason == "end_turn" or text-only responses without tool calls
• If agent provides text-only response indicating completion (keywords: "task complete", "finished", "done", "all files created"), treat as completion signal
• Add iteration counter and check if agent is repeating the same action (potential infinite loop detection)
• Return AgentStatus.COMPLETED instead of continuing to max_iterations

Add new method _is_completion_signal():

• Parse LLM response for completion indicators
• Check if response contains only text (no tool calls)
• Look for explicit completion phrases
• Return boolean

File: file:codeframe/core/events.py

Add new event type:

• AGENT_EARLY_COMPLETION - emitted when agent terminates before max_iterations

5. Configuration and Observability

File: file:codeframe/core/config.py

Add configuration options to EnvironmentConfig:

• react_agent_max_iterations: int = 30 - default max iterations
• react_agent_adaptive_budget: bool = True - enable adaptive budgeting
• react_agent_auto_fix: bool = True - enable automatic lint fixing
• react_agent_early_termination: bool = True - enable early termination

File: file:codeframe/core/react_agent.py

Enhance logging and events:

• Emit ITERATION_BUDGET_CALCULATED event with calculated budget and reasoning
• Log iteration count at each step: "Iteration X/Y"
• Emit AUTO_FIX_APPLIED event when auto-fix runs
• Track and log iteration usage breakdown: exploration, file creation, lint fixes, verification

6. Testing Considerations

File: file:tests/core/test_react_agent.py

Add test cases for:

• Adaptive budget calculation with various task complexities
• Auto-fix integration with successful and failed scenarios
• Early termination detection with completion signals
• Iteration budget not exceeded with new features

File: file:tests/core/test_gates.py

Add test cases for:

• run_autofix_on_file() with ruff and eslint
• Auto-fix success and failure scenarios

Sequence Diagram

sequenceDiagram
    participant User
    participant ReactAgent
    participant ContextLoader
    participant LLM
    participant AutoFix
    participant Gates

    User->>ReactAgent: run(task_id)
    ReactAgent->>ContextLoader: load(task_id)
    ContextLoader->>ContextLoader: _load_critical_files()
    ContextLoader-->>ReactAgent: TaskContext (enhanced)
    ReactAgent->>ReactAgent: _calculate_adaptive_budget()
    Note over ReactAgent: Budget: 30 + (5 files × 5) = 55
    ReactAgent->>ReactAgent: _build_system_prompt()
    Note over ReactAgent: Include pre-loaded files list
    
    loop Until completion or max_iterations
        ReactAgent->>LLM: generate(prompt)
        LLM-->>ReactAgent: response + tool_calls
        
        alt Has tool_calls
            ReactAgent->>ReactAgent: execute_tool()
            alt File write/edit
                ReactAgent->>AutoFix: _auto_fix_file(path)
                AutoFix-->>ReactAgent: fixed
                ReactAgent->>Gates: run_lint_on_file(path)
                Gates-->>ReactAgent: GateCheck
            end
        else Text-only response
            ReactAgent->>ReactAgent: _is_completion_signal()
            alt Is completion
                ReactAgent-->>User: AgentStatus.COMPLETED
            end
        end
    end
    
    ReactAgent->>Gates: run(workspace)
    Gates-->>ReactAgent: GateResult
    ReactAgent-->>User: AgentStatus

Loading

Expected Impact

After implementing these changes:

• Exploration overhead: Reduced from 9 to 2-3 iterations (saves 6-7 iterations)
• Per-file overhead: Reduced from 3-5 to 1-2 iterations (saves 2-3 iterations per file)
• Effective budget: Increased from ~21 to ~50+ iterations for multi-file tasks
• File capacity: Increased from 4-7 files to 10-12+ files per task
• Success rate: Multi-file tasks that previously failed at iteration 30 should now complete successfully

Import In IDE

🤖 Prompt for AI Agents

## Observations

The ReactAgent currently has a fixed 30-iteration budget that proves insufficient for multi-file tasks. Analysis shows: (1) ContextLoader already pre-loads relevant files but agents still spend ~9 iterations exploring, (2) each file creation requires 3-5 iterations for lint-fix cycles, (3) ruff auto-fix infrastructure exists in legacy `file:codeframe/core/agent.py` but isn't integrated into the ReactAgent's main loop, and (4) no early termination mechanism exists despite LLM responses including `stop_reason` signals.

## Approach

The plan addresses all four contributing factors through complementary improvements: enhance context pre-loading to eliminate exploration waste, implement adaptive iteration budgets based on task complexity, integrate ruff auto-fix into the ReactAgent's tool execution pipeline, and add early termination detection. This multi-pronged approach should increase effective budget from ~21 iterations (30 - 9 exploration) to ~25+ iterations while reducing per-file overhead from 3-5 to 1-2 iterations, enabling 10-12 files per task.

## Implementation Steps

### 1. Enhance Context Pre-Loading (Fix #373)

**Objective:** Reduce exploration iterations from 9 to 2-3 by improving what's included in the initial system prompt.

**File:** `file:codeframe/core/react_agent.py`

Modify `_build_system_prompt()` method to:
- Include more comprehensive file tree structure in the initial prompt
- Pre-load configuration files (pyproject.toml, package.json, .env.example, AGENTS.md, CLAUDE.md)
- Add explicit instructions about available files to discourage redundant exploration
- Include directory structure with file counts per directory
- Add a "Files Already Loaded" section listing all pre-loaded file paths

**File:** `file:codeframe/core/context.py`

Enhance `ContextLoader.load()` to:
- Automatically include critical configuration files regardless of relevance score
- Increase the number of files shown in repository structure from 100 to 200
- Add a new method `_load_critical_files()` that always loads: README.md, pyproject.toml, package.json, setup.py, requirements.txt, tsconfig.json
- Adjust relevance scoring to boost configuration and documentation files

### 2. Implement Adaptive Iteration Budget

**Objective:** Scale iteration budget based on task complexity indicators.

**File:** `file:codeframe/core/react_agent.py`

Add new method `_calculate_adaptive_budget()`:
- Analyze task description for complexity indicators (number of files mentioned, keywords like "multiple", "several", "all")
- Check if task has subtasks or dependencies
- Examine PRD length and complexity
- Calculate budget: base 30 + (estimated_files × 5) + (has_subtasks × 10)
- Cap maximum at 100 iterations to prevent runaway execution

Modify `__init__()`:
- Add parameter `adaptive_budget: bool = True`
- If enabled, call `_calculate_adaptive_budget()` to override `max_iterations`
- Log the calculated budget for observability

**File:** `file:codeframe/core/models.py`

Add task metadata fields if not present:
- `estimated_complexity: Optional[str]` (low/medium/high)
- `estimated_file_count: Optional[int]`

### 3. Integrate Ruff Auto-Fix into ReactAgent

**Objective:** Reduce lint-fix iterations from 3-5 to 1-2 by running auto-fix before lint gate.

**File:** `file:codeframe/core/react_agent.py`

Modify `_execute_tool_with_lint()` method:
- After successful file write/edit operations, automatically run `ruff check --fix {file}` if file extension is `.py` or `.pyi`
- Use the existing ruff infrastructure from `file:codeframe/core/gates.py`
- Only run the lint gate check after auto-fix completes
- Log auto-fix results for debugging

Add new method `_auto_fix_file()`:
- Accept file path as parameter
- Detect file type and select appropriate auto-fix tool (ruff for Python, eslint --fix for JS/TS)
- Run auto-fix command using subprocess with 30s timeout
- Return boolean indicating success/failure
- Emit event for observability

**File:** `file:codeframe/core/gates.py`

Add new function `run_autofix_on_file()`:
- Similar to `run_lint_on_file()` but runs with `--fix` flag
- Support ruff, eslint, and other fixable linters
- Return GateCheck with details of what was fixed
- Update LINTER_REGISTRY to include auto-fix commands

### 4. Add Early Termination via Stop Reason Detection

**Objective:** Allow agent to signal completion before hitting max_iterations.

**File:** `file:codeframe/core/react_agent.py`

Modify `_react_loop()` method:
- Check LLM response for `stop_reason == "end_turn"` or text-only responses without tool calls
- If agent provides text-only response indicating completion (keywords: "task complete", "finished", "done", "all files created"), treat as completion signal
- Add iteration counter and check if agent is repeating the same action (potential infinite loop detection)
- Return `AgentStatus.COMPLETED` instead of continuing to max_iterations

Add new method `_is_completion_signal()`:
- Parse LLM response for completion indicators
- Check if response contains only text (no tool calls)
- Look for explicit completion phrases
- Return boolean

**File:** `file:codeframe/core/events.py`

Add new event type:
- `AGENT_EARLY_COMPLETION` - emitted when agent terminates before max_iterations

### 5. Configuration and Observability

**File:** `file:codeframe/core/config.py`

Add configuration options to `EnvironmentConfig`:
- `react_agent_max_iterations: int = 30` - default max iterations
- `react_agent_adaptive_budget: bool = True` - enable adaptive budgeting
- `react_agent_auto_fix: bool = True` - enable automatic lint fixing
- `react_agent_early_termination: bool = True` - enable early termination

**File:** `file:codeframe/core/react_agent.py`

Enhance logging and events:
- Emit `ITERATION_BUDGET_CALCULATED` event with calculated budget and reasoning
- Log iteration count at each step: "Iteration X/Y"
- Emit `AUTO_FIX_APPLIED` event when auto-fix runs
- Track and log iteration usage breakdown: exploration, file creation, lint fixes, verification

### 6. Testing Considerations

**File:** `file:tests/core/test_react_agent.py`

Add test cases for:
- Adaptive budget calculation with various task complexities
- Auto-fix integration with successful and failed scenarios
- Early termination detection with completion signals
- Iteration budget not exceeded with new features

**File:** `file:tests/core/test_gates.py`

Add test cases for:
- `run_autofix_on_file()` with ruff and eslint
- Auto-fix success and failure scenarios

## Sequence Diagram

```mermaid
sequenceDiagram
    participant User
    participant ReactAgent
    participant ContextLoader
    participant LLM
    participant AutoFix
    participant Gates

    User->>ReactAgent: run(task_id)
    ReactAgent->>ContextLoader: load(task_id)
    ContextLoader->>ContextLoader: _load_critical_files()
    ContextLoader-->>ReactAgent: TaskContext (enhanced)
    ReactAgent->>ReactAgent: _calculate_adaptive_budget()
    Note over ReactAgent: Budget: 30 + (5 files × 5) = 55
    ReactAgent->>ReactAgent: _build_system_prompt()
    Note over ReactAgent: Include pre-loaded files list
    
    loop Until completion or max_iterations
        ReactAgent->>LLM: generate(prompt)
        LLM-->>ReactAgent: response + tool_calls
        
        alt Has tool_calls
            ReactAgent->>ReactAgent: execute_tool()
            alt File write/edit
                ReactAgent->>AutoFix: _auto_fix_file(path)
                AutoFix-->>ReactAgent: fixed
                ReactAgent->>Gates: run_lint_on_file(path)
                Gates-->>ReactAgent: GateCheck
            end
        else Text-only response
            ReactAgent->>ReactAgent: _is_completion_signal()
            alt Is completion
                ReactAgent-->>User: AgentStatus.COMPLETED
            end
        end
    end
    
    ReactAgent->>Gates: run(workspace)
    Gates-->>ReactAgent: GateResult
    ReactAgent-->>User: AgentStatus
```

## Expected Impact

After implementing these changes:

- **Exploration overhead**: Reduced from 9 to 2-3 iterations (saves 6-7 iterations)
- **Per-file overhead**: Reduced from 3-5 to 1-2 iterations (saves 2-3 iterations per file)
- **Effective budget**: Increased from ~21 to ~50+ iterations for multi-file tasks
- **File capacity**: Increased from 4-7 files to 10-12+ files per task
- **Success rate**: Multi-file tasks that previously failed at iteration 30 should now complete successfully

---

Execution Information

Branch: main
Commit: e04112c

---

💡 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]

🔗 Related PRs

#342 - feat: agent execution resilience - file conflicts, verification recovery, observability [merged]
#356 - fix: agent execution resilience + Phase 2.5 architecture research [merged]
#364 - feat: phase-based event emission for ReactAgent progress reporting [merged]
#366 - feat: language-aware per-edit lint gate in ReactAgent [merged]
#370 - feat: token budget tracking and message compaction for ReactAgent (#352) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 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!