fix: address runtime review follow-ups

Author: Telli

src/SharpClaw.Code.Agents/Internal/ProviderBackedAgentKernel.cs

@@ -254,7 +254,8 @@ internal async Task<ProviderInvocationResult> ExecuteAsync(
             }
 
             // Detect if the loop was exhausted (provider kept requesting tools every iteration).
-            if (iteration >= options.MaxToolIterations)
+            var toolLoopExhausted = iteration >= options.MaxToolIterations;
+            if (toolLoopExhausted)
             {
                 logger.LogWarning(
                     "Tool-calling loop reached maximum iterations ({MaxIterations}) for session {SessionId}; output may be incomplete.",
@@ -280,10 +281,14 @@ internal async Task<ProviderInvocationResult> ExecuteAsync(
                 TotalTokens: request.Context.Prompt.Length + output.Length,
                 EstimatedCostUsd: null);
 
+            var summary = toolLoopExhausted
+                ? $"Provider response from {resolvedProviderName}/{requestedModel} is incomplete because the tool-calling loop reached the maximum of {options.MaxToolIterations} iterations."
+                : $"Streamed provider response from {resolvedProviderName}/{requestedModel}.";
+
             return new ProviderInvocationResult(
                 Output: output,
                 Usage: usage,
-                Summary: $"Streamed provider response from {resolvedProviderName}/{requestedModel}.",
+                Summary: summary,
                 ProviderRequest: lastProviderRequest,
                 ProviderEvents: allProviderEvents,
                 ToolResults: allToolResults.Count > 0 ? allToolResults : null,

src/SharpClaw.Code.Runtime/Context/ConversationHistoryCache.cs

@@ -0,0 +1,100 @@
+using System.Collections.Concurrent;
+using SharpClaw.Code.Protocol.Models;
+
+namespace SharpClaw.Code.Runtime.Context;
+
+/// <summary>
+/// Caches assembled conversation history per session so follow-up turns can reuse
+/// in-process transcript state without rereading the full event log.
+/// </summary>
+internal static class ConversationHistoryCache
+{
+    internal const int MaxHistoryTokenBudget = 100_000;
+    private const int MaxCacheEntries = 100;
+    private static readonly ConcurrentDictionary<string, CacheEntry> Cache = new(StringComparer.Ordinal);
+
+    public static bool TryGet(
+        string workspaceRoot,
+        string sessionId,
+        int completedTurnSequence,
+        out IReadOnlyList<ChatMessage> history)
+    {
+        if (completedTurnSequence >= 0
+            && Cache.TryGetValue(CreateKey(workspaceRoot, sessionId), out var entry)
+            && entry.CompletedTurnSequence == completedTurnSequence)
+        {
+            history = entry.History;
+            return true;
+        }
+
+        history = [];
+        return false;
+    }
+
+    public static void Store(
+        string workspaceRoot,
+        string sessionId,
+        int completedTurnSequence,
+        IReadOnlyList<ChatMessage> history)
+    {
+        Cache[CreateKey(workspaceRoot, sessionId)] = new CacheEntry(completedTurnSequence, [.. history]);
+        EvictOverflow();
+    }
+
+    public static void StoreCompletedTurn(string workspaceRoot, string sessionId, ConversationTurn completedTurn)
+    {
+        ArgumentNullException.ThrowIfNull(completedTurn);
+        if (completedTurn.SequenceNumber <= 0 || string.IsNullOrWhiteSpace(completedTurn.Output))
+        {
+            return;
+        }
+
+        var previousSequence = completedTurn.SequenceNumber - 1;
+        IReadOnlyList<ChatMessage> priorHistory = [];
+        if (previousSequence > 0
+            && !TryGet(workspaceRoot, sessionId, previousSequence, out priorHistory))
+        {
+            return;
+        }
+
+        var updatedHistory = priorHistory
+            .Concat(
+            [
+                CreateMessage("user", completedTurn.Input),
+                CreateMessage("assistant", completedTurn.Output),
+            ])
+            .ToArray();
+
+        Store(
+            workspaceRoot,
+            sessionId,
+            completedTurn.SequenceNumber,
+            ContextWindowManager.Truncate(updatedHistory, MaxHistoryTokenBudget));
+    }
+
+    private static ChatMessage CreateMessage(string role, string text)
+        => new(role, [new ContentBlock(ContentBlockKind.Text, text, null, null, null, null)]);
+
+    private static string CreateKey(string workspaceRoot, string sessionId)
+        => $"{workspaceRoot}\u0000{sessionId}";
+
+    private static void EvictOverflow()
+    {
+        if (Cache.Count <= MaxCacheEntries)
+        {
+            return;
+        }
+
+        var overflowKeys = Cache.Keys
+            .OrderBy(static key => key, StringComparer.Ordinal)
+            .Take(Cache.Count - MaxCacheEntries)
+            .ToArray();
+
+        foreach (var key in overflowKeys)
+        {
+            Cache.TryRemove(key, out _);
+        }
+    }
+
+    private sealed record CacheEntry(int CompletedTurnSequence, ChatMessage[] History);
+}

src/SharpClaw.Code.Runtime/Context/PromptContextAssembler.cs

@@ -162,15 +162,19 @@ public async Task<PromptExecutionContext> AssembleAsync(
         // NOTE: This reads the full event log per turn, which scales linearly with session length.
         // For long-running sessions, consider persisting a compacted message history in session metadata
         // to avoid re-reading and re-assembling the full log on every prompt.
-        const int MaxHistoryTokenBudget = 100_000;
         IReadOnlyList<ChatMessage> conversationHistory = [];
         if (turn.SequenceNumber > 1)
         {
-            var sessionEvents = await eventStore
-                .ReadAllAsync(workspaceRoot, session.Id, cancellationToken)
-                .ConfigureAwait(false);
-            var rawHistory = ConversationHistoryAssembler.Assemble(sessionEvents);
-            conversationHistory = ContextWindowManager.Truncate(rawHistory, MaxHistoryTokenBudget);
+            var targetSequence = turn.SequenceNumber - 1;
+            if (!ConversationHistoryCache.TryGet(workspaceRoot, session.Id, targetSequence, out conversationHistory))
+            {
+                var sessionEvents = await eventStore
+                    .ReadAllAsync(workspaceRoot, session.Id, cancellationToken)
+                    .ConfigureAwait(false);
+                var rawHistory = ConversationHistoryAssembler.Assemble(sessionEvents);
+                conversationHistory = ContextWindowManager.Truncate(rawHistory, ConversationHistoryCache.MaxHistoryTokenBudget);
+                ConversationHistoryCache.Store(workspaceRoot, session.Id, targetSequence, conversationHistory);
+            }
         }
 
         return new PromptExecutionContext(

src/SharpClaw.Code.Runtime/Diagnostics/WorkspaceDiagnosticsService.cs

@@ -59,7 +59,7 @@ public async Task<WorkspaceDiagnosticsSnapshot> BuildSnapshotAsync(string worksp
 
         var snapshot = new WorkspaceDiagnosticsSnapshot(workspaceRoot, systemClock.UtcNow, configuredServers, diagnostics);
         Cache[workspaceRoot] = snapshot;
-        EvictStaleCacheEntries();
+        EvictCacheEntries();
         return snapshot;
     }
 
@@ -98,13 +98,8 @@ private static IEnumerable<WorkspaceDiagnosticItem> ParseDotnetDiagnostics(strin
     private static string? NullIfEmpty(string value)
         => string.IsNullOrWhiteSpace(value) ? null : value;
 
-    private void EvictStaleCacheEntries()
+    private void EvictCacheEntries()
     {
-        if (Cache.Count <= MaxCacheEntries)
-        {
-            return;
-        }
-
         var now = systemClock.UtcNow;
         foreach (var key in Cache.Keys)
         {
@@ -113,6 +108,23 @@ private void EvictStaleCacheEntries()
                 Cache.TryRemove(key, out _);
             }
         }
+
+        if (Cache.Count <= MaxCacheEntries)
+        {
+            return;
+        }
+
+        var overflowKeys = Cache
+            .OrderBy(static pair => pair.Value.GeneratedAtUtc)
+            .ThenBy(static pair => pair.Key, StringComparer.Ordinal)
+            .Take(Cache.Count - MaxCacheEntries)
+            .Select(static pair => pair.Key)
+            .ToArray();
+
+        foreach (var key in overflowKeys)
+        {
+            Cache.TryRemove(key, out _);
+        }
     }
 
     [GeneratedRegex(@"^(?<path>.*?)(?:\((?<line>\d+),(?<column>\d+)\))?:\s*(?<severity>error|warning)\s*(?<code>[A-Z]{2,}\d+)?\s*:?\s*(?<message>.+)$", RegexOptions.Multiline | RegexOptions.IgnoreCase)]

src/SharpClaw.Code.Runtime/Orchestration/ConversationRuntime.cs

@@ -14,6 +14,7 @@
 using SharpClaw.Code.Runtime.CustomCommands;
 using SharpClaw.Code.Runtime.Diagnostics;
 using SharpClaw.Code.Runtime.Export;
+using SharpClaw.Code.Runtime.Context;
 using SharpClaw.Code.Runtime.Lifecycle;
 using SharpClaw.Code.Runtime.Mutations;
 using SharpClaw.Code.Runtime.Turns;
@@ -269,6 +270,7 @@ await AppendEventAsync(
                 CompletedAtUtc = completedAtUtc,
                 Usage = turnRunResult.Usage,
             };
+            ConversationHistoryCache.StoreCompletedTurn(workspacePath, session.Id, completedTurn);
 
             await AppendRuntimeEventsAsync(
                 workspacePath,

src/SharpClaw.Code.Runtime/Server/WorkspaceHttpServer.cs

@@ -1,6 +1,7 @@
 using System.Net;
 using System.Text;
 using System.Text.Json;
+using System.Text.Json.Serialization.Metadata;
 using Microsoft.Extensions.Logging;
 using SharpClaw.Code.Protocol.Commands;
 using SharpClaw.Code.Protocol.Enums;
@@ -258,11 +259,7 @@ private static async Task<int> WriteCommandResultAsync(HttpListenerResponse resp
         }
     }
 
-    private static readonly JsonSerializerOptions ServerJsonOptions = new(JsonSerializerDefaults.Web)
-    {
-        DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull,
-        Converters = { new System.Text.Json.Serialization.JsonStringEnumConverter() },
-    };
+    private static readonly JsonSerializerOptions ServerJsonOptions = CreateServerJsonOptions();
 
     private static async Task WriteJsonAsync(HttpListenerResponse response, int statusCode, object payload, CancellationToken cancellationToken)
     {
@@ -283,10 +280,22 @@ private Task DispatchServerHookAsync(string workspaceRoot, HttpListenerRequest r
                 path,
                 statusCode,
                 succeeded,
-                DateTimeOffset.UtcNow));
+                DateTimeOffset.UtcNow),
+            ServerJsonOptions);
         return hookDispatcher.DispatchAsync(workspaceRoot, HookTriggerKind.ServerRequestCompleted, payload, CancellationToken.None);
     }
 
+    private static JsonSerializerOptions CreateServerJsonOptions()
+    {
+        var options = new JsonSerializerOptions(ProtocolJsonContext.Default.Options)
+        {
+            TypeInfoResolver = JsonTypeInfoResolver.Combine(
+                ProtocolJsonContext.Default,
+                new DefaultJsonTypeInfoResolver()),
+        };
+        return options;
+    }
+
     private sealed record ServerCommandEnvelope(
         bool Succeeded,
         int ExitCode,

tests/SharpClaw.Code.IntegrationTests/Runtime/AgentToolPolicyIntegrationTests.cs

@@ -1,6 +1,7 @@
 using System.Runtime.CompilerServices;
 using FluentAssertions;
 using Microsoft.Extensions.DependencyInjection;
+using SharpClaw.Code.Agents.Configuration;
 using SharpClaw.Code.Infrastructure.Abstractions;
 using SharpClaw.Code.Infrastructure.Models;
 using SharpClaw.Code.Permissions.Abstractions;
@@ -9,6 +10,7 @@
 using SharpClaw.Code.Plugins.Models;
 using SharpClaw.Code.Protocol.Commands;
 using SharpClaw.Code.Protocol.Enums;
+using SharpClaw.Code.Protocol.Events;
 using SharpClaw.Code.Protocol.Models;
 using SharpClaw.Code.Providers.Abstractions;
 using SharpClaw.Code.Providers.Models;
@@ -200,14 +202,55 @@ public async Task RunPrompt_should_deny_provider_requested_tool_that_is_not_in_a
         shellExecutor.CallCount.Should().Be(0);
     }
 
+    /// <summary>
+    /// Ensures callers can distinguish an incomplete provider result when the tool loop hits its iteration cap.
+    /// </summary>
+    [Fact]
+    public async Task RunPrompt_should_surface_tool_loop_exhaustion()
+    {
+        var workspacePath = CreateTemporaryWorkspace();
+        await File.WriteAllTextAsync(Path.Combine(workspacePath, "README.md"), "SharpClaw");
+
+        var provider = new CapturingToolPolicyProvider(ToolPolicyScenario.ExhaustToolLoop);
+        using var serviceProvider = CreateServiceProvider(provider, configureLoop: options => options.MaxToolIterations = 2);
+        var runtime = serviceProvider.GetRequiredService<IConversationRuntime>();
+
+        var result = await runtime.RunPromptAsync(
+            new RunPromptRequest(
+                Prompt: "keep reading the file",
+                SessionId: null,
+                WorkingDirectory: workspacePath,
+                PermissionMode: PermissionMode.WorkspaceWrite,
+                OutputFormat: OutputFormat.Text,
+                Metadata: new Dictionary<string, string>
+                {
+                    ["provider"] = TestProviderName,
+                    ["model"] = "tool-policy-model",
+                    [SharpClawWorkflowMetadataKeys.AgentAllowedToolsJson] = """["read_file"]""",
+                    [ScenarioMetadataKey] = ToolPolicyScenario.ExhaustToolLoop,
+                },
+                IsInteractive: true),
+            CancellationToken.None);
+
+        result.FinalOutput.Should().Contain("maximum of 2 iterations");
+        var completedEvent = result.Events.OfType<AgentCompletedEvent>().Should().ContainSingle().Subject;
+        completedEvent.Summary.Should().Contain("maximum of 2 iterations");
+    }
+
     private static ServiceProvider CreateServiceProvider(
         CapturingToolPolicyProvider provider,
         RecordingApprovalService? approvalService = null,
         RecordingShellExecutor? shellExecutor = null,
-        IPluginManager? pluginManager = null)
+        IPluginManager? pluginManager = null,
+        Action<AgentLoopOptions>? configureLoop = null)
     {
         var services = new ServiceCollection();
         services.AddSharpClawRuntime();
+        if (configureLoop is not null)
+        {
+            services.Configure(configureLoop);
+        }
+
         services.AddSingleton<IProviderRequestPreflight, PassthroughPreflight>();
         services.AddSingleton<IAuthFlowService, AlwaysAuthenticatedAuthFlowService>();
         services.AddSingleton<IModelProviderResolver>(_ => new StaticModelProviderResolver(provider));
@@ -244,6 +287,7 @@ private static class ToolPolicyScenario
     {
         public const string CaptureOnly = "capture-only";
         public const string ToolRoundTrip = "tool-round-trip";
+        public const string ExhaustToolLoop = "exhaust-tool-loop";
     }
 
     private sealed class PassthroughPreflight : IProviderRequestPreflight
@@ -316,6 +360,24 @@ private static async IAsyncEnumerable<ProviderEvent> StreamEventsAsync(
                 yield break;
             }
 
+            if (string.Equals(scenario, ToolPolicyScenario.ExhaustToolLoop, StringComparison.Ordinal))
+            {
+                yield return new ProviderEvent(
+                    "provider-event-loop",
+                    request.Id,
+                    "tool_use",
+                    DateTimeOffset.UtcNow,
+                    null,
+                    false,
+                    null,
+                    BlockType: "tool_use",
+                    ToolUseId: $"toolu_read_{request.Messages?.Count ?? 0:D3}",
+                    ToolName: "read_file",
+                    ToolInputJson: """{"path":"README.md"}""");
+                yield return new ProviderEvent("provider-event-loop-terminal", request.Id, "completed", DateTimeOffset.UtcNow, null, true, new UsageSnapshot(1, 2, 0, 3, null));
+                yield break;
+            }
+
             yield return new ProviderEvent("provider-event-1", request.Id, "delta", DateTimeOffset.UtcNow, "ok", false, null);
             await Task.Yield();
             yield return new ProviderEvent("provider-event-2", request.Id, "completed", DateTimeOffset.UtcNow, null, true, new UsageSnapshot(1, 2, 0, 3, null));