feat: Add progress reporting and context overflow protection for agentic tools

- Add per-step progress notifications via MCP protocol during agent execution
- Thread ProgressCallback through Builder → Executor → Factory → Server chain
- Emit "Step N: Calling tool_name" notifications for user visibility

- Add per-tool result truncation in GraphToolExecutor (max_result_bytes)
- Intelligently truncates large results with _truncated metadata for agent awareness
- Add context accumulation guard in CodeGraphChatAdapter (max_context_bytes)
- Fail fast with clear error when accumulated context exceeds safe threshold

- Reduce tier-based max steps from 5/10/15/20 to 3/5/6/8
- Add hard cap at 8 steps (10 with env override) to prevent runaway costs
- Fix env var: check CODEGRAPH_CONTEXT_WINDOW before CODEGRAPH_LLM_CONTEXT_WINDOW

- Update README with new step limits table and context overflow protection docs

Author: jruokola

README.md

@@ -104,24 +104,52 @@ Running a small local model? Get focused, efficient queries.
 
 Using GPT-5.1 or Claude with 200K context? Get comprehensive, exploratory analysis.
 
-Using grok-4-1-fast-reasoning with 2M context? Get incredibly comprehensive up-to 40 turns spanning in-depth analyses.
+Using grok-4-1-fast-reasoning with 2M context? Get detailed analysis with intelligent result management.
 
 The Agent only uses the amount of steps that it requires to produce the answer so tool execution times vary based on the query and amount of data indexed in the database.
 
-During development the agent used 3-10 steps on average to produce answers for test scenarios.
+During development the agent used 3-6 steps on average to produce answers for test scenarios.
 
 The Agent is stateless it only has conversational memory for the span of tool execution it does not accumulate context/memory over multiple chained tool calls this is already handled by your client of choice, it accumulates that context so codegraph needs to just provide answers.
 
 | Your Model | CodeGraph's Behavior |
 |------------|---------------------|
-| < 50K tokens | Terse prompts, max 5 steps |
-| 50K-150K | Balanced analysis, max 10 steps |
-| 150K-500K | Detailed exploration, max 15 steps |
-| > 500K (Grok, etc.) | Full monty, max 20 steps |
+| < 50K tokens | Terse prompts, max 3 steps |
+| 50K-150K | Balanced analysis, max 5 steps |
+| 150K-500K | Detailed exploration, max 6 steps |
+| > 500K (Grok, etc.) | Comprehensive analysis, max 8 steps |
+
+**Hard cap:** Maximum 8 steps regardless of tier (10 with env override). This prevents runaway costs and context overflow while still allowing thorough analysis.
 
 **Same tool, automatically optimized for your setup.**
 
-### 4. Hybrid Search That Actually Works
+### 4. Context Overflow Protection
+
+CodeGraph includes multi-layer protection against context overflow—preventing expensive failures when tool results exceed your model's limits.
+
+**Per-Tool Result Truncation:**
+- Each tool result is limited based on your configured context window
+- Large results (e.g., dependency trees with 1000+ nodes) are intelligently truncated
+- Truncated results include `_truncated: true` metadata so the agent knows data was cut
+- Array results keep the most relevant items that fit within limits
+
+**Context Accumulation Guard:**
+- Monitors total accumulated context across multi-step reasoning
+- Fails fast with clear error message if accumulated tool results exceed safe threshold
+- Threshold: 80% of context window × 4 (conservative estimate for token overhead)
+
+**Configure via environment:**
+```bash
+# CRITICAL: Set this to match your agent's LLM context window
+CODEGRAPH_CONTEXT_WINDOW=128000  # Default: 128K
+
+# Per-tool result limit derived automatically: context_window × 2 bytes
+# Accumulation limit derived automatically: context_window × 4 × 0.8 bytes
+```
+
+**Why this matters:** Without these guards, a single `agentic_dependency_analysis` on a large codebase could return 6M+ tokens—far exceeding most models' limits and causing expensive failures.
+
+### 5. Hybrid Search That Actually Works
 
 We don't pick sides in the "embeddings vs keywords" debate. CodeGraph combines:
 

crates/codegraph-mcp-autoagents/src/autoagents/agent_builder.rs

@@ -15,7 +15,7 @@ use autoagents::llm::{FunctionCall, ToolCall};
 use codegraph_ai::llm_provider::{LLMProvider as CodeGraphLLM, Message, MessageRole};
 use codegraph_mcp_core::debug_logger::DebugLogger;
 use serde::Deserialize;
-use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
 use std::sync::Arc;
 
 /// Convert CodeGraph Message to AutoAgents ChatMessage
@@ -50,15 +50,76 @@ pub(crate) fn read_memory_window_config() -> usize {
         .unwrap_or(DEFAULT_MEMORY_WINDOW)
 }
 
+use crate::autoagents::progress_notifier::ProgressCallback;
+
 /// Adapter that bridges codegraph_ai::LLMProvider to AutoAgents ChatProvider
 pub struct CodeGraphChatAdapter {
     provider: Arc<dyn CodeGraphLLM>,
     tier: ContextTier,
+    progress_callback: Option<ProgressCallback>,
+    step_counter: Arc<AtomicUsize>,
+    /// Maximum context size in bytes (derived from CODEGRAPH_CONTEXT_WINDOW)
+    /// Used as safety valve to prevent accumulated tool results from exceeding model limits
+    max_context_bytes: usize,
 }
 
 impl CodeGraphChatAdapter {
+    /// Calculate max context bytes from environment or tier
+    /// Uses ~80% of context window (reserves 20% for response) at ~4 bytes/token
+    fn calculate_max_context_bytes(tier: ContextTier) -> usize {
+        // Check env var first
+        if let Ok(context_window) = std::env::var("CODEGRAPH_CONTEXT_WINDOW")
+            .ok()
+            .and_then(|v| v.parse::<usize>().ok())
+            .ok_or(())
+        {
+            // 80% of context window * 4 bytes/token
+            return context_window * 4 * 8 / 10;
+        }
+
+        // Fall back to tier-based defaults (tokens * 4 bytes * 80%)
+        match tier {
+            ContextTier::Small => 50_000 * 4 * 8 / 10,     // ~160KB
+            ContextTier::Medium => 128_000 * 4 * 8 / 10,   // ~410KB
+            ContextTier::Large => 200_000 * 4 * 8 / 10,    // ~640KB
+            ContextTier::Massive => 2_000_000 * 4 * 8 / 10, // ~6.4MB
+        }
+    }
+
     pub fn new(provider: Arc<dyn CodeGraphLLM>, tier: ContextTier) -> Self {
-        Self { provider, tier }
+        let max_context_bytes = Self::calculate_max_context_bytes(tier);
+        tracing::debug!(
+            "CodeGraphChatAdapter initialized with max_context_bytes: {} ({:.1}MB)",
+            max_context_bytes,
+            max_context_bytes as f64 / 1_000_000.0
+        );
+        Self {
+            provider,
+            tier,
+            progress_callback: None,
+            step_counter: Arc::new(AtomicUsize::new(1)),
+            max_context_bytes,
+        }
+    }
+
+    pub fn with_progress_callback(
+        provider: Arc<dyn CodeGraphLLM>,
+        tier: ContextTier,
+        callback: ProgressCallback,
+    ) -> Self {
+        let max_context_bytes = Self::calculate_max_context_bytes(tier);
+        tracing::debug!(
+            "CodeGraphChatAdapter initialized with max_context_bytes: {} ({:.1}MB)",
+            max_context_bytes,
+            max_context_bytes as f64 / 1_000_000.0
+        );
+        Self {
+            provider,
+            tier,
+            progress_callback: Some(callback),
+            step_counter: Arc::new(AtomicUsize::new(1)),
+            max_context_bytes,
+        }
     }
 
     /// Convert AutoAgents Tool to CodeGraph ToolDefinition
@@ -165,6 +226,46 @@ impl ChatProvider for CodeGraphChatAdapter {
             })
             .collect();
 
+        // Safety valve: Check accumulated context size before sending to LLM
+        let total_context_bytes: usize = cg_messages.iter().map(|m| m.content.len()).sum();
+        if total_context_bytes > self.max_context_bytes {
+            let overflow_ratio = total_context_bytes as f64 / self.max_context_bytes as f64;
+            tracing::error!(
+                total_bytes = total_context_bytes,
+                max_bytes = self.max_context_bytes,
+                overflow_ratio = format!("{:.1}x", overflow_ratio),
+                message_count = cg_messages.len(),
+                "CONTEXT OVERFLOW: Accumulated messages exceed max_context_bytes limit"
+            );
+
+            // Return error instead of letting the API reject with a cryptic message
+            return Err(LLMError::Generic(format!(
+                "Context overflow: {} bytes exceeds {} byte limit ({:.1}x). \
+                 Tool results accumulated too much data. Try reducing result limits or query scope.",
+                total_context_bytes,
+                self.max_context_bytes,
+                overflow_ratio
+            )));
+        }
+
+        // Log context usage for monitoring
+        let usage_percent = (total_context_bytes as f64 / self.max_context_bytes as f64) * 100.0;
+        if usage_percent > 70.0 {
+            tracing::warn!(
+                total_bytes = total_context_bytes,
+                max_bytes = self.max_context_bytes,
+                usage_percent = format!("{:.1}%", usage_percent),
+                "Context usage above 70% - approaching limit"
+            );
+        } else {
+            tracing::debug!(
+                total_bytes = total_context_bytes,
+                max_bytes = self.max_context_bytes,
+                usage_percent = format!("{:.1}%", usage_percent),
+                "Context size within limits"
+            );
+        }
+
         // Convert AutoAgents tools to CodeGraph ToolDefinitions
         let cg_tools = tools.map(Self::convert_tools);
 
@@ -212,6 +313,32 @@ impl ChatProvider for CodeGraphChatAdapter {
             response.finish_reason
         );
 
+        // Emit step progress notification if callback is configured
+        if let Some(ref callback) = self.progress_callback {
+            let step = self.step_counter.fetch_add(1, Ordering::SeqCst);
+            let tool_names = response
+                .tool_calls
+                .as_ref()
+                .map(|tc| {
+                    tc.iter()
+                        .map(|t| t.function.name.as_str())
+                        .collect::<Vec<_>>()
+                        .join(", ")
+                })
+                .filter(|s| !s.is_empty());
+
+            let message = match tool_names {
+                Some(names) => format!("Step {}: Calling {}", step, names),
+                None => format!("Step {}: Agent reasoning...", step),
+            };
+
+            // Fire-and-forget progress notification (non-blocking)
+            let cb = callback.clone();
+            tokio::spawn(async move {
+                cb(step as f64, Some(message)).await;
+            });
+        }
+
         // Wrap response in AutoAgents ChatResponse with native tool calls
         Ok(Box::new(CodeGraphChatResponse {
             content: response.content,
@@ -675,6 +802,26 @@ impl CodeGraphAgentBuilder {
         }
     }
 
+    /// Create builder with progress callback for step-by-step notifications
+    pub fn with_progress_callback(
+        llm_provider: Arc<dyn codegraph_ai::llm_provider::LLMProvider>,
+        tool_executor: Arc<GraphToolExecutor>,
+        tier: ContextTier,
+        analysis_type: AnalysisType,
+        callback: ProgressCallback,
+    ) -> Self {
+        Self {
+            llm_adapter: Arc::new(CodeGraphChatAdapter::with_progress_callback(
+                llm_provider,
+                tier,
+                callback,
+            )),
+            tool_factory: GraphToolFactory::new(tool_executor),
+            tier,
+            analysis_type,
+        }
+    }
+
     pub async fn build(self) -> Result<AgentHandle, AutoAgentsError> {
         // Get tier-aware configuration and system prompt
         let tier_plugin = TierAwarePromptPlugin::new(self.analysis_type, self.tier);

crates/codegraph-mcp-autoagents/src/autoagents/executor.rs

@@ -2,6 +2,7 @@
 // ABOUTME: Orchestrates architecture detection, factory-based executor creation, and delegation
 
 use crate::autoagents::codegraph_agent::CodeGraphAgentOutput;
+use crate::autoagents::progress_notifier::ProgressCallback;
 use crate::autoagents::startup_context::{build_startup_context, StartupContextRender};
 use codegraph_ai::llm_provider::LLMProvider;
 use codegraph_graph::{GraphFunctions, HubNode};
@@ -116,11 +117,37 @@ impl CodeGraphExecutor {
         llm_provider: Arc<dyn LLMProvider>,
         tool_executor: Arc<GraphToolExecutor>,
         config: Arc<codegraph_mcp_core::config_manager::CodeGraphConfig>,
+    ) -> Self {
+        Self::with_optional_progress_callback(llm_provider, tool_executor, config, None)
+    }
+
+    pub fn with_progress_callback(
+        llm_provider: Arc<dyn LLMProvider>,
+        tool_executor: Arc<GraphToolExecutor>,
+        config: Arc<codegraph_mcp_core::config_manager::CodeGraphConfig>,
+        callback: ProgressCallback,
+    ) -> Self {
+        Self::with_optional_progress_callback(llm_provider, tool_executor, config, Some(callback))
+    }
+
+    fn with_optional_progress_callback(
+        llm_provider: Arc<dyn LLMProvider>,
+        tool_executor: Arc<GraphToolExecutor>,
+        config: Arc<codegraph_mcp_core::config_manager::CodeGraphConfig>,
+        progress_callback: Option<ProgressCallback>,
     ) -> Self {
         use crate::autoagents::executor_factory::AgentExecutorFactory;
 
         // Create factory for architecture-specific executors
-        let factory = AgentExecutorFactory::new(llm_provider, tool_executor, config.clone());
+        let factory = match progress_callback {
+            Some(callback) => AgentExecutorFactory::with_progress_callback(
+                llm_provider,
+                tool_executor,
+                config.clone(),
+                callback,
+            ),
+            None => AgentExecutorFactory::new(llm_provider, tool_executor, config.clone()),
+        };
 
         // Detect architecture from environment or config
         let architecture = AgentExecutorFactory::detect_architecture();
@@ -293,6 +320,7 @@ pub struct CodeGraphExecutorBuilder {
     llm_provider: Option<Arc<dyn LLMProvider>>,
     tool_executor: Option<Arc<GraphToolExecutor>>,
     config: Option<Arc<codegraph_mcp_core::config_manager::CodeGraphConfig>>,
+    progress_callback: Option<ProgressCallback>,
 }
 
 impl CodeGraphExecutorBuilder {
@@ -301,6 +329,7 @@ impl CodeGraphExecutorBuilder {
             llm_provider: None,
             tool_executor: None,
             config: None,
+            progress_callback: None,
         }
     }
 
@@ -322,6 +351,12 @@ impl CodeGraphExecutorBuilder {
         self
     }
 
+    /// Set progress callback for step-by-step notifications
+    pub fn progress_callback(mut self, callback: ProgressCallback) -> Self {
+        self.progress_callback = Some(callback);
+        self
+    }
+
     pub fn build(self) -> Result<CodeGraphExecutor, ExecutorError> {
         let llm_provider = self
             .llm_provider
@@ -337,7 +372,15 @@ impl CodeGraphExecutorBuilder {
             Arc::new(codegraph_mcp_core::config_manager::CodeGraphConfig::default())
         });
 
-        Ok(CodeGraphExecutor::new(llm_provider, tool_executor, config))
+        // Create executor with or without progress callback
+        let executor = match self.progress_callback {
+            Some(callback) => {
+                CodeGraphExecutor::with_progress_callback(llm_provider, tool_executor, config, callback)
+            }
+            None => CodeGraphExecutor::new(llm_provider, tool_executor, config),
+        };
+
+        Ok(executor)
     }
 }