fix(agent): increase tool iteration limit from 10 to 25 and add budget awareness

[louisdevzz]

Summary

Fixes #26 by increasing the agent tool iteration limit and adding budget awareness to prevent task failures on complex multi-step operations.

Problem statement

The agent was limited to 10 tool iterations, causing failures on complex tasks like building a Next.js project. When a user requested a landing page website, the agent would:

1. Setup sandbox (iteration 1)
2. Create Next.js project (iteration 2)
3. Install dependencies (iteration 3)
4. Write page.tsx (iteration 4)
5. Write layout.tsx (iteration 5)
6. Start dev server (iteration 6)
7. Read package.json to verify (iteration 7)
8. List files in root (iteration 8)
9. List files in cat-coffee/ (iteration 9)
10. List files in project/ (iteration 10)

❌ Agent exceeded the 10-tool limit and failed before providing the preview URL to the user.

This caused:

• Tasks failing after significant work was done
• Wasted resources (sandbox created, dependencies installed, server started)
• Poor user experience with no completion or failure message
• No way to recover or resume from where it stopped

Proposed solution

1. Increase Iteration Limit (10 → 25)

Update the default maximum tool iterations to accommodate complex multi-step tasks:

• Change DEFAULT_MAX_TOOL_ITERATIONS from 10 to 25 in src/agent/loop_.rs
• Change default_agent_max_tool_iterations() from 10 to 25 in src/config/schema.rs
• Update documentation comments to reflect the new default

2. Add Budget Awareness to System Prompt

Inject iteration budget information into the agent's system prompt so it can plan efficiently:

## Tool Use Budget

You have a maximum of 25 tool-use iterations to complete this task.
Plan efficiently:

- Complex tasks (build projects, multiple files): ~15-20 iterations
- Medium tasks (modify existing code): ~8-12 iterations
- Simple tasks (read files, explain): ~3-5 iterations

If approaching the limit, prioritize:
1. Complete the critical path first (create → build → verify)
2. Skip verification steps if already confident
3. Provide partial results with explanation rather than failing

This helps the agent:

• Understand its resource constraints
• Plan operations more efficiently
• Prioritize critical path over verification
• Know when to provide partial results

Changes

• src/agent/loop_.rs:

  • Update DEFAULT_MAX_TOOL_ITERATIONS constant from 10 to 25
  • Add iteration budget section to system prompt

• src/config/schema.rs:

  • Update default_agent_max_tool_iterations() from 10 to 25
  • Update documentation comments

Acceptance criteria

• Tool iteration limit increased from 10 to 25
• Default configuration updated in schema.rs
• Budget awareness added to system prompt
• Code compiles without errors (cargo check passes)
• No breaking changes to existing functionality
• Backward compatible (respects user config if explicitly set)
• Fixes [Bug]: Agent exceeds maximum tool iteration limit (10) causing task failure #26

Testing

• Code compiles successfully with cargo check
• No breaking changes to existing functionality
• Backward compatible (respects user config if set)

Risk and Rollback

Risk: Increased resource usage from more tool calls.
Mitigation: Limit still enforced at 25; agent is now aware and plans better.

Rollback:

• Revert commit to restore 10-iteration limit
• Or set max_tool_iterations: 10 in config

Breaking Change?

No

Existing configs with explicit max_tool_iterations values are respected. Only the default changes.

[github-actions]

PR Intake Checks - Warnings (non-blocking)

The following are recommendations:

• Missing sections: Problem statement, Proposed solution, Acceptance criteria

[coderabbitai]

Warning

Rate limit exceeded

@louisdevzz has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 8 minutes and 46 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: cc8a732f-3624-4636-aa62-541605d05377

📥 Commits

Reviewing files that changed from the base of the PR and between f16df7f and 868aa22.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (11)

• src/agent/loop_.rs
• src/channels/mod.rs
• src/config/schema.rs
• src/sandbox/mod.rs
• src/tools/github_ops.rs
• src/tools/mod.rs
• src/tools/sandbox/create.rs
• src/tools/sandbox/package_manager.rs
• tests/agent_loop_robustness.rs
• tests/config_persistence.rs
• tests/config_schema.rs

Note

.coderabbit.yaml has unrecognized properties

CodeRabbit is using all valid settings from your configuration. Unrecognized properties (listed below) have been ignored and may indicate typos or deprecated fields that can be removed.

⚠️ Parsing warnings (1)

Validation error: Unrecognized key(s) in object: 'version', 'tests', 'ignore'

⚙️ Configuration instructions

• Please see the configuration documentation for more information.
• You can also validate your configuration using the online YAML validator.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Walkthrough

The pull request increases the default agent tool-iteration limit from 10 to 25 and introduces a "Tool Use Budget" section to the system prompt. This section communicates the iteration budget to the model with tiered guidance for task planning and priorities if approaching the limit.

Changes

Cohort / File(s)	Summary
Tool Iteration Limit & Budget Guidance src/agent/loop_.rs, src/config/schema.rs	Increased max_tool_iterations default from 10 to 25. Added a new "Tool Use Budget" section injected into the system prompt that communicates the iteration budget and provides tiered guidance for task planning (Complex/Medium/Simple tasks). Updated configuration documentation to reflect the new default and rationale.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Linked Issues check	❓ Inconclusive	The PR addresses issue #26 by increasing iteration limit (10→25) and adding budget awareness. However, several objectives remain unimplemented: graceful degradation, resume capability, state persistence, and optimized batching strategies.	Clarify whether partial objectives are intentional (addressed in this PR vs. future work) or if resume/graceful-degradation mechanisms should be included. Consider tracking unaddressed objectives in follow-up issues.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and accurately summarizes the main changes: increasing the tool iteration limit and adding budget awareness to prevent task failures.
Description check	✅ Passed	The description covers problem statement, solution, changes, acceptance criteria, testing, and rollback plan. Some template sections are missing (labels, security impact, i18n), but core content is well-documented.
Out of Scope Changes check	✅ Passed	All changes are directly related to the stated objectives: two files modified (loop_.rs and schema.rs) with focused updates to the iteration limit constant and default configuration function.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/agent-iteration-limit

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (2)

src/config/schema.rs (1)

545-547: Add explicit compatibility/rollback note in the field docs.

This documents the new default well, but it should also state compatibility and rollback explicitly (e.g., explicit user configs are unchanged; set max_tool_iterations = 10 to revert behavior).
As per coding guidelines, for src/config/*.rs changes, treat keys as public contract and document defaults, compatibility impact, and migration/rollback path.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/config/schema.rs` around lines 545 - 547, Update the field doc comment
for max_tool_iterations to explicitly state compatibility and rollback guidance:
note that this change only alters the default (public contract key
"max_tool_iterations") and does not change explicit user configurations,
describe the compatibility impact for existing setups, and provide a clear
rollback/migration instruction such as "to restore previous behavior set
max_tool_iterations = 10" so users know how to revert; ensure this text appears
alongside the existing default/behavior note in src/config/schema.rs near the
max_tool_iterations field.

src/agent/loop_.rs (1)

3024-3033: Static tier ranges can contradict configured low limits.

When configured max is small (e.g., 5–10), the fixed “Complex: ~15–20” guidance conflicts with the actual cap and can push poor planning. Consider deriving these ranges from max_iterations.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/agent/loop_.rs` around lines 3024 - 3033, The hardcoded tier ranges in
the system prompt can contradict a low configured cap; compute dynamic ranges
from the existing max_iterations variable (derived from
config.agent.max_tool_iterations) and replace the fixed "15–20 / 8–12 / 3–5"
text in the system_prompt.push_str call with derived values (e.g., set simple ≈
max*0.25 rounded, medium ≈ max*0.5, complex ≈ max*0.8, and clamp minimums to
sensible floors like 1–2) so the guidance reflects the actual limit; update the
system_prompt formatting logic where system_prompt.push_str(...) is called to
inject these computed ranges instead of the static strings.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/agent/loop_.rs`:
- Around line 3024-3033: The budget-awareness text block is only appended to
system_prompt inside the run path, so the process_message flow never receives
the tool-use guidance; extract the logic that computes max_iterations (using
config.agent.max_tool_iterations and DEFAULT_MAX_TOOL_ITERATIONS) and the
formatted budget string into a reusable helper (e.g., build_tool_budget_prompt
or add_tool_budget_to_prompt) and call it from both run and process_message
where system_prompt is constructed; ensure the helper accepts/configures the
same symbols (max_iterations, config.agent.max_tool_iterations) and
appends/returns the exact formatted string so both prompt-construction paths
include the same budget guidance.

In `@src/config/schema.rs`:
- Around line 561-563: The default in fn default_agent_max_tool_iterations() was
changed to 25 but tests still expect 10; update any tests that assert the
previous default (e.g., the agent_config_defaults test) to assert 25 instead of
10 so the test suite passes, and run cargo fmt, cargo clippy, and cargo test to
verify no other defaults mismatch.

---

Nitpick comments:
In `@src/agent/loop_.rs`:
- Around line 3024-3033: The hardcoded tier ranges in the system prompt can
contradict a low configured cap; compute dynamic ranges from the existing
max_iterations variable (derived from config.agent.max_tool_iterations) and
replace the fixed "15–20 / 8–12 / 3–5" text in the system_prompt.push_str call
with derived values (e.g., set simple ≈ max*0.25 rounded, medium ≈ max*0.5,
complex ≈ max*0.8, and clamp minimums to sensible floors like 1–2) so the
guidance reflects the actual limit; update the system_prompt formatting logic
where system_prompt.push_str(...) is called to inject these computed ranges
instead of the static strings.

In `@src/config/schema.rs`:
- Around line 545-547: Update the field doc comment for max_tool_iterations to
explicitly state compatibility and rollback guidance: note that this change only
alters the default (public contract key "max_tool_iterations") and does not
change explicit user configurations, describe the compatibility impact for
existing setups, and provide a clear rollback/migration instruction such as "to
restore previous behavior set max_tool_iterations = 10" so users know how to
revert; ensure this text appears alongside the existing default/behavior note in
src/config/schema.rs near the max_tool_iterations field.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 097e9c72-1caf-4ae1-820c-aaa8a80f0ebd

📥 Commits

Reviewing files that changed from the base of the PR and between c6f8b70 and f16df7f.

📒 Files selected for processing (2)

• src/agent/loop_.rs
• src/config/schema.rs