Turn Processing Loop

Relevant source files

• src/acp/zed/agent/handlers.rs
• src/acp/zed/agent/mod.rs
• src/acp/zed/agent/session_state.rs
• src/acp/zed/types.rs
• src/agent/agents.rs
• src/agent/runloop/unified/context_manager.rs
• src/agent/runloop/unified/context_manager_tests.rs
• src/agent/runloop/unified/incremental_system_prompt.rs
• src/agent/runloop/unified/incremental_system_prompt_tests.rs
• src/agent/runloop/unified/run_loop_context.rs
• src/agent/runloop/unified/session_setup.rs
• src/agent/runloop/unified/status_line.rs
• src/agent/runloop/unified/tool_pipeline.rs
• src/agent/runloop/unified/turn/context.rs
• src/agent/runloop/unified/turn/guards.rs
• src/agent/runloop/unified/turn/session/interaction_loop.rs
• src/agent/runloop/unified/turn/session/interaction_loop_runner.rs
• src/agent/runloop/unified/turn/session_loop.rs
• src/agent/runloop/unified/turn/session_loop_runner.rs
• src/agent/runloop/unified/turn/tool_outcomes.rs
• src/agent/runloop/unified/turn/tool_outcomes/execution_result.rs
• src/agent/runloop/unified/turn/tool_outcomes/handlers.rs
• src/agent/runloop/unified/turn/turn_loop.rs
• src/agent/runloop/unified/turn/turn_processing.rs
• src/agent/runloop/unified/turn/turn_processing/llm_request.rs
• src/agent/runloop/unified/ui_interaction.rs
• src/cli/sessions.rs
• vtcode-core/src/core/agent/events/mod.rs
• vtcode-core/src/core/agent/runner.rs
• vtcode-core/src/core/agent/runner/execute.rs
• vtcode-core/src/core/agent/session/controller.rs
• vtcode-core/src/core/mod.rs
• vtcode-core/src/core/threads.rs
• vtcode-core/src/lib.rs
• vtcode-core/src/utils/session_archive.rs

This document describes the turn-based execution model of VT Code's agent runtime, focusing on the core processing loop that drives LLM interaction, tool execution, and response handling within a single turn.

Scope: This page covers the turn loop implementation (src/agent/runloop/unified/turn/turn_loop.rs), turn processing contexts, phase transitions, and the integration between LLM requests and tool execution. For broader agent execution orchestration, see Agent Runner. For context and prompt management, see Context Management. For tool execution details, see Tool System.

---

Turn Loop Architecture

The turn processing loop is the core execution unit of the agent. Each turn represents a complete interaction cycle: building a system prompt, sending an LLM request, processing the response, executing any requested tool calls, and handling the outcome.

Core Components

The turn loop architecture consists of three primary structures:

TurnLoopContext src/agent/runloop/unified/turn/turn_loop.rs45-162

• Top-level context containing all resources needed for turn execution
• Includes UI handles (InlineHandle, InlineSession), tool registries, LLM provider, configuration, and state trackers
• Constructed once per turn and passed through the execution flow
• Provides as_turn_processing_context() method to create refined context views

TurnProcessingContext src/agent/runloop/unified/turn/context.rs151-245

• Refined context structure created from TurnLoopContext
• Organized into logical component groups: ToolContext, LLMContext, UIContext, TurnProcessingState
• Provides structured access to subsystems during turn execution
• Created via from_parts() constructor with TurnProcessingContextParts

HarnessTurnState src/agent/runloop/unified/run_loop_context.rs64-203

• Tracks turn-level execution metrics and budgets via fields: tool_calls, blocked_tool_calls, max_tool_calls, turn_started_at
• Monitors tool call counts, blocked call streaks, and timeout tracking
• Enforces per-turn limits through methods: tool_budget_exhausted(), wall_clock_exhausted(), remaining_tool_calls()

Sources: src/agent/runloop/unified/turn/turn_loop.rs45-244 src/agent/runloop/unified/turn/context.rs88-299 src/agent/runloop/unified/run_loop_context.rs64-203

---

Turn Execution Phases

Each turn progresses through four distinct phases tracked by TurnPhase enum src/agent/runloop/unified/run_loop_context.rs28-33:

Phase	Purpose	Key Operations
Preparing	Pre-request validation and setup	Proactive guards, safety validator initialization, turn state reset
Requesting	LLM request construction and execution	System prompt building, message history normalization, streaming response handling
ExecutingTools	Tool call validation and execution	Permission checks, circuit breaker validation, tool execution pipeline
Finalizing	Result aggregation and cleanup	Turn outcome emission, telemetry recording, history updates

Sources: src/agent/runloop/unified/turn/turn_loop.rs319-323 src/agent/runloop/unified/turn/turn_loop.rs391-403 src/agent/runloop/unified/turn/turn_loop.rs593-602 src/agent/runloop/unified/turn/turn_loop.rs660-673

---

Main Turn Loop Flow

The run_turn_loop function src/agent/runloop/unified/turn/turn_loop.rs301-680 orchestrates the entire turn execution cycle:

Sources: src/agent/runloop/unified/turn/turn_loop.rs301-680 src/agent/runloop/unified/turn/guards.rs199-213 src/agent/runloop/unified/turn/turn_processing/llm_request.rs477-1084 src/agent/runloop/unified/turn/turn_processing/response_processing.rs src/agent/runloop/unified/turn/turn_processing/result_handler.rs

Step-by-Step Breakdown

1. Initialization src/agent/runloop/unified/turn/turn_loop.rs314-346

• Set initial result to Completed
• Reset auto_exit_plan_mode_attempted flag
• Initialize LoopTracker for repetition detection
• Configure max_tool_loops from turn config
• Reset safety validator with turn limits
• Clear turn-level loop detection state

2. Steering Messages src/agent/runloop/unified/turn/turn_loop_helpers.rs

• Check for external steering commands (e.g., from Zed integration)
• Handle commands like model switching, exit requests
• Return early if exit/cancellation requested

3. Pre-Request Action src/agent/runloop/unified/turn/turn_loop_helpers.rs

• Execute lifecycle hooks if configured
• Check Ctrl+C state for cancellation
• Validate turn hasn't exceeded time/call budgets

4. Plan Mode Exit Trigger src/agent/runloop/unified/turn/turn_loop_helpers.rs

• Check if plan mode should auto-exit (after sufficient planning)
• Transition to edit mode if triggered

5. Tool Loop Limit src/agent/runloop/unified/turn/turn_loop_helpers.rs

• Enforce max_tool_loops per turn
• Prompt for limit increase if interactive mode
• Break turn if limit exhausted

6. Proactive Guards src/agent/runloop/unified/turn/guards.rs199-213

• Auto-prune decision ledgers to prevent memory growth
• Currently minimal; retained for future extensibility

7. LLM Request Execution src/agent/runloop/unified/turn/turn_processing/llm_request.rs

• Build system prompt via ContextManager
• Normalize message history
• Execute streaming LLM request with retry logic
• Track token usage and update context manager

8. Response Processing src/agent/runloop/unified/turn/turn_processing/response_processing.rs

• Parse LLM response for tool calls vs text response
• Validate tool arguments against schemas
• Handle interview synthesis in plan mode

9. Turn Result Handling src/agent/runloop/unified/turn/turn_processing/result_handler.rs

• Dispatch tool calls for execution
• Handle text responses and reasoning
• Track modified files
• Return Continue or Break(outcome)

10. Token Usage Update src/agent/runloop/unified/turn/turn_loop.rs644-653

• Update ContextManager with provider-reported usage
• Validate token tracking consistency (debug builds)

Sources: src/agent/runloop/unified/turn/turn_loop.rs301-680 src/agent/runloop/unified/turn/guards.rs199-213

---

LLM Request and Response Processing

Request Assembly

The execute_llm_request function src/agent/runloop/unified/turn/turn_processing/llm_request.rs477-1084 orchestrates LLM request construction:

Key optimizations:

• Tool catalog caching: Reuse Vec<uni::ToolDefinition> when config/plan mode unchanged via tool_catalog.get_or_build() src/agent/runloop/unified/turn/turn_processing/llm_request.rs648-697
• Retry with compaction: Truncate tool output messages via compact_tool_messages_for_retry() to max 1200 chars per message src/agent/runloop/unified/turn/turn_processing/llm_request.rs274-303
• Streaming fallback: Disable streaming for providers in STREAM_TIMEOUT_FALLBACK_PROVIDERS array after timeout src/agent/runloop/unified/turn/turn_processing/llm_request.rs42-51 src/agent/runloop/unified/turn/turn_processing/llm_request.rs253-264
• Prompt cache shaping: Resolve PromptCacheShapingMode via resolve_prompt_cache_shaping_mode() for Anthropic/MiniMax src/agent/runloop/unified/turn/turn_processing/llm_request.rs66-84
• Error classification: Use vtcode_commons::classify_error_message() for structured retry decisions src/agent/runloop/unified/turn/turn_processing/llm_request.rs38-40

Sources: src/agent/runloop/unified/turn/turn_processing/llm_request.rs477-1084 src/agent/runloop/unified/turn/turn_processing/llm_request.rs648-697 src/agent/runloop/unified/turn/turn_processing/llm_request.rs274-303 src/agent/runloop/unified/turn/turn_processing/llm_request.rs42-51

Response Processing

The process_llm_response function src/agent/runloop/unified/turn/turn_processing/response_processing.rs parses and validates LLM responses:

Response Type	Validation	Output
Tool calls	validate_tool_args_security()	TurnProcessingResult::ToolCalls
Text with proposed plan	Extract plan from markdown blocks	TurnProcessingResult::TextResponse with proposed_plan
Plain text	Basic content extraction	TurnProcessingResult::TextResponse
Empty/whitespace	No actionable content	TurnProcessingResult::Empty

Validation flow src/agent/runloop/unified/turn/guards.rs20-179:

1. Cache lookup using argument hash
2. Registry-based preflight validation if available
3. Required argument checks (tool-specific)
4. Security checks (path safety, command safety)
5. Cache insertion on success

Sources: src/agent/runloop/unified/turn/turn_processing/response_processing.rs src/agent/runloop/unified/turn/guards.rs20-179

---

Tool Execution Within Turns

Tool execution within a turn follows a multi-stage pipeline with extensive validation and safety checks:

Sources: src/agent/runloop/unified/turn/turn_processing/result_handler.rs src/agent/runloop/unified/turn/tool_outcomes/handlers.rs src/agent/runloop/unified/turn/tool_outcomes/handlers_batch.rs src/agent/runloop/unified/turn/tool_outcomes/execution_result.rs431-504 src/agent/runloop/unified/turn/guards.rs20-179 src/agent/runloop/unified/tool_pipeline.rs

Tool Call Validation Stages

Stage 1: Circuit Breaker Check src/agent/runloop/unified/turn/tool_outcomes/handlers.rs63-85

• Query circuit_breaker.is_open(canonical_tool_name)
• If OPEN, call try_interactive_circuit_recovery() which:
  • Checks error_recovery.can_prompt_user() for cooldown
  • Builds recovery prompt from diagnostics and open circuits
  • Executes execute_recovery_prompt() with RecoveryAction enum
  • Options: ResetAllCircuits, Continue, SkipStep, SaveAndExit
• Default fallback: circuit_breaker_default_blocked() returns ValidationResult::Blocked

Stage 2: Argument Validation src/agent/runloop/unified/turn/guards.rs20-179

• Hash-based cache lookup via validation_cache.check(name, args_hash)
• Preflight validation via tool_registry.preflight_validate_call(name, args) if registry available
• Required parameter checks using static slices: &["path"], &["command"], etc.
• Security checks:
  • paths::validate_path_safety(path) for path arguments
  • commands::validate_command_safety(cmd) for command arguments
• Cache insertion via validation_cache.insert(name, args_hash, is_valid)

Stage 3: Rate Limiting src/agent/runloop/unified/turn/tool_outcomes/handlers.rs55-57

• Retry loop: for attempt in 0..MAX_RATE_LIMIT_ACQUIRE_ATTEMPTS (4 attempts)
• rate_limiter.try_acquire(canonical_tool_name, 1)?
• Exponential backoff: tokio::time::sleep(backoff_duration).await
• Returns build_rate_limit_error_content() if exhausted

Stage 4: Permission Verification src/agent/runloop/unified/tool_routing.rs

• Check tool_permission_cache.check_permission(tool_name, args)
• Call ensure_tool_permission() which:
  • Queries tool_policy_manager.check_policy()
  • Executes ToolPermissionFlow::execute() for prompt/deny policies
  • Caches result in tool_permission_cache
• Full-auto mode uses approval_policy_from_human_in_the_loop() for MCP tools

Sources: src/agent/runloop/unified/turn/tool_outcomes/handlers.rs55-214 src/agent/runloop/unified/turn/guards.rs20-179 src/agent/runloop/unified/tool_routing.rs

Execution Pipeline

Once validated, tools execute through a timeout-wrapped pipeline src/agent/runloop/unified/tool_pipeline.rs:

1. Timeout wrapper src/agent/runloop/unified/tool_pipeline.rs27-32

   • DEFAULT_TOOL_TIMEOUT = 180 seconds
   • apply_timeout_with_warning() with MIN_TIMEOUT_WARNING_HEADROOM = 5 seconds
   • Enforces max_tool_timeout from tool policy configuration

2. Retry logic src/agent/runloop/unified/tool_pipeline/execution_attempts.rs

   • Up to 3 retries for transient failures (configurable via max_tool_retries)
   • Exponential backoff: RETRY_BACKOFF_BASE = 200ms, MAX_RETRY_BACKOFF = 3s
   • Error classification via is_retryable_tool_error() for retry decisions

3. Sandbox application src/agent/runloop/unified/tool_pipeline/execution_plan_mode.rs

   • Check is_read_only_operation() for plan mode restrictions
   • Apply SandboxManager transformations for high-risk commands
   • Enforce workspace boundary constraints

4. Output handling src/agent/runloop/unified/tool_pipeline/execution.rs

   • ToolOutputSpooler for outputs exceeding DEFAULT_SPOOL_THRESHOLD
   • Summarizers via apply_tool_summarizer() for large results
   • Render via handle_pipeline_output_from_turn_ctx()

5. Metric recording src/agent/runloop/unified/turn/tool_outcomes/execution_result.rs27-47

   • circuit_breaker.record_execution(tool_name, success, duration)
   • tool_health_tracker.record_execution(tool_name, success, duration)
   • autonomous_executor.record_execution(tool_name, success)
   • telemetry.record_tool_usage(tool_name, success)

Sources: src/agent/runloop/unified/tool_pipeline.rs27-32 src/agent/runloop/unified/tool_pipeline/execution_attempts.rs src/agent/runloop/unified/tool_pipeline/execution.rs src/agent/runloop/unified/turn/tool_outcomes/execution_result.rs27-47

---

Turn Outcomes and Result Handling

The turn loop concludes with one of five possible outcomes:

Sources: src/agent/runloop/unified/turn/turn_loop.rs660-712 src/agent/runloop/unified/turn/context.rs32-39

Result Propagation

Turn outcomes propagate through multiple layers:

Layer	Structure	Purpose
Turn Loop	TurnLoopResult	Final turn status (Completed, Aborted, etc.)
Turn Handler	TurnHandlerOutcome	Intermediate control flow (Continue, Break)
Turn Processing	TurnProcessingResult	LLM response classification (ToolCalls, TextResponse)
Tool Batch	ToolBatchOutcome	Tool execution batch status
Tool Pipeline	ToolPipelineOutcome	Individual tool execution result

Sources: src/agent/runloop/unified/turn/context.rs32-74 src/agent/runloop/unified/tool_pipeline.rs24

Error Recovery

The turn loop includes recovery logic for post-tool LLM failures src/agent/runloop/unified/turn/turn_loop.rs252-297:

Recovery logic src/agent/runloop/unified/turn/turn_loop.rs260-297:

1. Check has_tool_response_since(working_history, turn_history_start_len)
   • Returns false if no tool progress: abort recovery
2. Classify error via vtcode_commons::classify_anyhow_error(err)
   • Get ErrorCategory with is_retryable() method
3. Render recovery message with transient hint if applicable
4. Log with category and retryability metadata
5. Return true to complete turn gracefully, preserving partial tool output

Recovery conditions:

• Tool responses were added to history between turn_history_start_len and current length
• Error category indicates potential transient nature (optional, advisory only)
• User-facing guidance provided via err_cat.user_label() and recovery_suggestions()

Call sites src/agent/runloop/unified/turn/turn_loop.rs:

• Line 433: After execute_llm_request() failure
• Line 529: After process_llm_response() failure
• Line 627: After handle_turn_processing_result() failure

If recovery succeeds, the turn completes with Completed status despite the LLM failure, preserving tool output. This prevents tool re-execution on retry.

Sources: src/agent/runloop/unified/turn/turn_loop.rs252-297 src/agent/runloop/unified/turn/turn_loop.rs246-250 src/agent/runloop/unified/turn/turn_loop.rs406-471 src/agent/runloop/unified/turn/turn_loop.rs527-542

---

Turn State Tracking and Budgets

The HarnessTurnState structure src/agent/runloop/unified/run_loop_context.rs64-203 enforces per-turn resource limits:

Budget Enforcement

Metric	Field	Check Method	Threshold Source	Action on Exhaustion
Tool calls	tool_calls: usize / max_tool_calls: usize	tool_budget_exhausted() line 99	harness.max_tool_calls config	Emit budget warning at 75% via should_emit_tool_budget_warning(0.75) line 102 stop at 100%
Wall clock	turn_started_at: Instant + max_tool_wall_clock: Duration	wall_clock_exhausted() line 92	harness.max_tool_wall_clock_secs config	Stop turn, return TurnLoopResult::Blocked with timeout reason
Blocked streak	consecutive_blocked_tool_calls: usize	record_blocked_tool_call() line 120 returns streak count	tools.max_consecutive_blocked_tool_calls_per_turn from config	Call enforce_blocked_tool_call_guard() which stops turn after limit exceeded
Spool reads	consecutive_spool_chunk_reads: usize	record_spool_chunk_read() line 159	tools.max_sequential_spool_chunk_reads_per_turn	Apply offset hints via maybe_apply_spool_read_offset_hint() to auto-advance
Shell repeats	last_shell_command_signature: Option<String>, consecutive_same_shell_command_runs: usize	record_shell_command_run(signature) line 168	tools.max_repeated_tool_calls from config	Block via build_repeated_shell_run_error_content() after limit

Sources: src/agent/runloop/unified/run_loop_context.rs64-203 src/agent/runloop/unified/turn/tool_outcomes/handlers.rs294-343

Loop Detection

The turn loop tracks repetitive patterns across three dimensions:

1. Tool Call Signatures src/agent/runloop/unified/turn/tool_outcomes/helpers.rs

• Canonical signatures for deduplication: "tool_name::normalized_args"
• Exponential backoff warnings when loops detected
• Forced diversity after threshold exceeded

2. Shell Command Signatures src/agent/runloop/unified/run_loop_context.rs168-183

• Track last command signature
• Increment streak counter on exact match
• Reset streak on new command

3. Spool Chunk Reads src/agent/runloop/unified/run_loop_context.rs159-166

• Auto-advance offset hints for sequential reads
• Prevent redundant chunk re-reads
• Apply continuation args automatically

Sources: src/agent/runloop/unified/turn/tool_outcomes/helpers.rs src/agent/runloop/unified/run_loop_context.rs159-183

---

Turn Metrics and Telemetry

The turn loop emits structured metrics for observability:

Metric Events

Turn Lifecycle src/agent/runloop/unified/turn/turn_loop.rs320-322

• turn_started_event(): Emitted at turn initialization
• turn_completed_event(): Emitted on success/exit
• turn_failed_event(): Emitted on abort/block/cancel

Tool Catalog Cache src/agent/runloop/unified/turn/turn_processing/llm_request.rs362-407

LLM Retry Outcome src/agent/runloop/unified/turn/turn_processing/llm_request.rs410-474

Tool Execution src/agent/runloop/unified/turn/tool_outcomes/execution_result.rs27-47

• Record execution in ToolHealthTracker
• Update CircuitBreaker with success/failure
• Log to TelemetryManager
• Track autonomous execution patterns

Sources: src/agent/runloop/unified/turn/turn_loop.rs320-322 src/agent/runloop/unified/turn/turn_processing/llm_request.rs362-474 src/agent/runloop/unified/turn/tool_outcomes/execution_result.rs27-47

---

Turn Loop Configuration

Turn loop behavior is controlled by configuration from multiple sources:

Turn Config Extraction

The extract_turn_config function src/agent/runloop/unified/turn/turn_loop_helpers.rs consolidates configuration:

Configuration sources:

1. vtcode.toml [tools] section
2. Plan mode overrides (e.g., unlimited turns in plan mode)
3. Runtime defaults (defined in vtcode-config/constants)

Key Configuration Parameters

Parameter	Path	Default	Impact
max_tool_calls	harness.max_tool_calls	25	Tool budget per turn
max_tool_wall_clock_secs	harness.max_tool_wall_clock_secs	300	Wall clock timeout per turn
max_tool_retries	harness.max_tool_retries	3	Retry budget for failed tools
max_repeated_tool_calls	tools.max_repeated_tool_calls	3	Loop detection threshold
max_consecutive_blocked_tool_calls_per_turn	tools.max_consecutive_blocked_tool_calls_per_turn	5	Blocked streak limit
max_sequential_spool_chunk_reads_per_turn	tools.max_sequential_spool_chunk_reads_per_turn	8	Spool read limit

Sources: src/agent/runloop/unified/turn/turn_loop_helpers.rs vtcode-config/src/constants/defaults.rs

---

Integration with Session Loop

The turn loop is invoked by the session interaction loop src/agent/runloop/unified/turn/session/interaction_loop.rs172-177:

Sources: src/agent/runloop/unified/turn/session/interaction_loop.rs172-177

---

Advanced Features

Steering Messages

Steering messages enable external control over turn execution via tokio::sync::mpsc::UnboundedReceiver<SteeringMessage> vtcode-core/src/core/agent/steering.rs:

Processing src/agent/runloop/unified/turn/turn_loop_helpers.rs:

• Checked at line 349 via handle_steering_messages(&mut ctx, working_history, &mut result).await?
• Reads from ctx.steering_receiver via try_recv() (non-blocking)
• SwitchModel: Updates ctx.config.model and recreates ctx.provider_client
• Exit/Cancel: Sets result and returns early from turn loop
• Called before each LLM request to ensure responsiveness

Integration points:

• Zed ACP integration: Sends steering messages from IDE
• CLI signal handlers: Convert Ctrl+C to steering messages
• Future: Agent-to-agent coordination via steering channels

Sources: src/agent/runloop/unified/turn/turn_loop_helpers.rs vtcode-core/src/core/agent/steering.rs src/agent/runloop/unified/turn/turn_loop.rs349-351

Plan Mode Interview Synthesis

In plan mode, the turn loop can synthesize interview questions from assistant responses src/agent/runloop/unified/turn/turn_processing/plan_mode.rs:

1. Check if response warrants interview (via should_attempt_dynamic_interview_generation)
2. Send secondary LLM request to generate structured questions
3. Force-inject request_user_input tool call with synthesized args
4. User answers questions, responses feed back into next turn

Sources: src/agent/runloop/unified/turn/turn_processing/plan_mode.rs

Harness Event Emission

For external integrations (e.g., Zed via ACP), the turn loop emits structured events src/agent/runloop/unified/inline_events/harness.rs:

• turn_started_event()
• turn_completed_event()
• turn_failed_event()
• Item-level events for streaming content

Sources: src/agent/runloop/unified/turn/turn_loop.rs320-322 src/agent/runloop/unified/turn/turn_loop.rs660-672