[Bug]: Agent exceeds maximum tool iteration limit (10) causing task failure

[louisdevzz]

Summary

Agent exceeds maximum tool iteration limit (10) during task execution, causing abrupt termination and task failure. This occurs when the agent makes excessive sequential tool calls without proper planning.

Affected component

runtime/agent

Severity

S1 - workflow blocked

Current behavior

When processing a user request (creating a landing page), the agent exceeded the maximum allowed tool iterations:

[AGENT] Executing tool: sandbox_create
[AGENT] Executing tool: sandbox_run_command (create-next-app)
[AGENT] Executing tool: sandbox_run_command (pnpm install)
[AGENT] Executing tool: sandbox_write_file (page.tsx)
[AGENT] Executing tool: sandbox_write_file (layout.tsx)
[AGENT] Executing tool: sandbox_run_command (pnpm run dev)
[AGENT] Executing tool: sandbox_read_file (package.json)
[AGENT] Executing tool: sandbox_list_files (.)
[AGENT] Executing tool: sandbox_list_files (cat-coffee)
[AGENT] Executing tool: sandbox_list_files (project)
❌ LLM error after 349277ms: Agent exceeded maximum tool iterations (10)

Problems caused:

1. Task fails abruptly without completion
2. Server started with pnpm run dev but user never received preview URL
3. User left without confirmation of success or failure
4. No recovery mechanism - agent cannot resume from where it stopped
5. Wasted computation resources (sandbox created, dependencies installed, dev server started)

Expected behavior

The agent should:

1. Plan efficiently: Group related operations to minimize tool calls
2. Respect iteration limits: Stay within the 10-tool budget per turn
3. Prioritize actions: Focus on critical path (setup → build → verify → provide URL)
4. Provide graceful degradation: If approaching limit, complete current phase and pause
5. Resume capability: Store state to resume interrupted tasks

Optimal tool sequence for this task (6 tools):

1. sandbox_create
2. sandbox_run_command (create-next-app + install deps in one command)
3. sandbox_write_file (page.tsx)
4. sandbox_write_file (layout.tsx)
5. sandbox_run_command (build/start)
6. sandbox_get_preview_url

Steps to reproduce

1. Request a complex task from agent (e.g., "Create a landing page website")
2. Agent creates sandbox and scaffold project
3. Agent installs dependencies
4. Agent writes multiple files
5. Agent starts dev server
6. Agent attempts to verify setup by listing files repeatedly
7. Bug: Agent exceeds 10-tool limit before completing task

Specific request that triggered bug:

bạn tạo giúp tôi 1 website landing page coffee mèo nhé

Impact

Affected users: All users requesting multi-step tasks
Frequency: Intermittent - depends on agent's tool usage pattern
Consequence:

• Tasks fail after significant work is done
• Resources wasted (sandbox, installed deps, running server)
• Poor user experience - no completion or failure message
• User cannot easily retry without starting over

Logs / stack traces

2026-03-04T18:15:14.336851Z  INFO zerobuild::sandbox::local: Local sandbox created at /var/folders/bp/6_t36vds31147b3mgpc3wjg40000gn/T/zerobuild-sandbox-cf971429-6ddd-4767-983d-4239f5aedf9a
[AGENT] Executing tool: sandbox_run_command with args: Object {"command": String("npx create-next-app@latest cat-coffee --typescript --tailwind --eslint --app --src-dir --import-alias \"@/*\" --yes"), "timeout_ms": Number(300000)}
2026-03-04T18:17:56.597295Z  WARN zerobuild::providers::reliable: Provider call failed, retrying provider="kimi-code" model="kimi-k2.5" attempt=1 backoff_ms=500 reason="retryable"
2026-03-04T18:17:59.589227Z  INFO zerobuild::providers::reliable: Provider recovered (failover/retry) provider="kimi-code" model="kimi-k2.5" attempt=1 original_model="kimi-k2.5"
[AGENT] Executing tool: sandbox_run_command with args: Object {"command": String("cd cat-coffee && pnpm install framer-motion lucide-react"), "timeout_ms": Number(120000)}
[AGENT] Executing tool: sandbox_write_file with args: Object {"content": String("..."), "path": String("cat-coffee/src/app/page.tsx")}
[AGENT] Executing tool: sandbox_write_file with args: Object {"content": String("..."), "path": String("cat-coffee/src/app/layout.tsx")}
[AGENT] Executing tool: sandbox_run_command with args: Object {"command": String("cd cat-coffee && pnpm run dev"), "timeout_ms": Number(60000)}
[AGENT] Executing tool: sandbox_read_file with args: Object {"path": String(".../package.json")}
[AGENT] Executing tool: sandbox_list_files with args: Object {"path": String(".")}
[AGENT] Executing tool: sandbox_list_files with args: Object {"path": String("cat-coffee")}
[AGENT] Executing tool: sandbox_list_files with args: Object {"path": String("project")}
❌ LLM error after 349277ms: Agent exceeded maximum tool iterations (10)

Root cause analysis

1. Excessive verification: Agent called sandbox_list_files 3 times to verify structure
2. No iteration budget awareness: Agent doesn't track or optimize tool usage
3. Sequential dependencies: Each file write requires separate tool call
4. No batching: Could combine operations (e.g., install all deps in one command)

ZeroBuild version

Latest main branch (2026-03-04)

Rust version

rustc 1.92.0

Operating system

macOS (affects all platforms)

Regression?

No, first-time setup

Pre-flight checks

• I reproduced this on the latest main branch or latest release.
• I redacted secrets/tokens from logs.
• I removed personal identifiers and replaced identity-specific data with neutral placeholders.