Prompt-Caching, Tool-Ergebnis-Kappung und Kostenerfassung

T1 — Prompt-Caching. Bisher wurde bei jedem Schritt eines Runs der komplette
Prompt neu berechnet, inklusive Tool-Definitionen und System-Prompt, die sich nie
aendern. Bei zehn Schritten und einem 15k-Praefix sind das 150.000 statt 15.000
Eingabe-Tokens.

ChatMessage bekommt dafuer einen eigenen JsonConverter: Der Inhalt geht weiterhin
als String raus, bei gesetztem CacheBreakpoint jedoch als Blockarray mit
cache_control. Beim Lesen werden beide Formate akzeptiert, damit bestehende
ChatContext.json weiter geladen werden koennen.

PromptCache setzt zwei Breakpoints: einen auf den System-Prompt (deckt
Tool-Definitionen und System-Prompt ab) und einen rollierenden auf die letzte
Nachricht mit Inhalt. Vorherige Markierungen werden vorher entfernt, damit sie
sich nicht ansammeln. Aktivierung ueber promptCaching: auto (Default, aktiv fuer
Modelle mit Unterstuetzung), on oder off.

Der wichtigste Test dazu prueft die Praefix-Stabilitaet: Der System-Prompt muss
ueber alle Schritte zeichengleich serialisiert werden. Ein einziger Zeitstempel
darin wuerde den Cache still verwerfen — die Kosten blieben unveraendert, ohne
dass es irgendwo auffiele.

T9 — Usage liest prompt_tokens_details.cached_tokens; die Zahl wird bis in
AgentRunResult durchgereicht. Ohne sie liesse sich die Wirkung nicht belegen.

T2 — Tool-Ergebnisse werden jetzt zentral in ExecuteToolCallAsync gekappt
(maxToolResultChars, Default 16.000). Bisher konnte ein einzelner WebFetch mit
dem 512-KB-Standardlimit rund 130.000 Tokens in EINER Antwort erzeugen; die
Compaction griff erst danach, bezahlt war der Request laengst.

T3 — Die Zusammenfassung beim Kompaktieren laeuft ueber ein konfigurierbares
summaryModel (Default gemini-2.5-flash) statt ueber das teure Agentenmodell.

B4 — AgentRunResult fuehrt Prompt- und Completion-Tokens getrennt; die
Kostenanzeige schaetzte bisher 50/50, real liegt das Verhaeltnis eher bei 95:5.
Die veraltete Preistabelle bleibt offen.

Neue Einstellungen sind im PropertyGrid sichtbar und werden vom AgentEditor bei
neuen Agenten mitgeschrieben.

Alle 91 Tests gruen.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Models/AgentSettingsViewModel.cs

@@ -3,6 +3,16 @@ using ClawdDotNet.Core.Config;
 
 namespace ClawdDotNet.Models;
 
+/// <summary>Bietet die drei gültigen Prompt-Caching-Werte als Auswahlliste an.</summary>
+public sealed class PromptCachingConverter : StringConverter
+{
+    public override bool GetStandardValuesSupported(ITypeDescriptorContext? context) => true;
+    public override bool GetStandardValuesExclusive(ITypeDescriptorContext? context) => true;
+
+    public override StandardValuesCollection GetStandardValues(ITypeDescriptorContext? context)
+        => new(new[] { "auto", "on", "off" });
+}
+
 [TypeConverter(typeof(ExpandableObjectConverter))]
 public sealed class AgentSettingsViewModel
 {
@@ -106,6 +116,42 @@ public sealed class AgentSettingsViewModel
         set => _config.LoopGuard.CompactionThreshold = Math.Clamp(value, 50, 95) / 100.0;
     }
 
+    [Category("3 - Kontext-Management")]
+    [DisplayName("Modell für Zusammenfassungen")]
+    [Description("Modell, mit dem beim Kompaktieren zusammengefasst wird. Leer = Modell des Agenten. " +
+                 "Zusammenfassen ist anspruchslos — ein günstiges Modell spart hier deutlich, " +
+                 "da bis zu 30.000 Zeichen verarbeitet werden.")]
+    public string SummaryModel
+    {
+        get => _config.LoopGuard.SummaryModel;
+        set => _config.LoopGuard.SummaryModel = value ?? "";
+    }
+
+    [Category("3 - Kontext-Management")]
+    [DisplayName("Max. Zeichen pro Tool-Ergebnis")]
+    [Description("Längere Tool-Ergebnisse werden gekürzt, bevor sie in den Kontext gelangen. " +
+                 "Ohne Grenze kann ein einzelner Abruf den Kontext sprengen — 512 KB entsprechen " +
+                 "etwa 130.000 Tokens in einer einzigen Antwort.")]
+    public int MaxToolResultChars
+    {
+        get => _config.MaxToolResultChars;
+        set => _config.MaxToolResultChars = Math.Max(1_000, value);
+    }
+
+    // ──────────────── Kosten ────────────────
+
+    [Category("5 - Kosten")]
+    [DisplayName("Prompt-Caching")]
+    [Description("auto = für Modelle aktivieren, die es unterstützen; on = erzwingen; off = aus. " +
+                 "Spart erheblich, weil jeder Schritt eines Runs den kompletten Prompt erneut sendet — " +
+                 "System-Prompt und Tool-Definitionen also dutzendfach.")]
+    [TypeConverter(typeof(PromptCachingConverter))]
+    public string PromptCaching
+    {
+        get => _config.PromptCaching;
+        set => _config.PromptCaching = string.IsNullOrWhiteSpace(value) ? "auto" : value;
+    }
+
     // ──────────────── Tools (Read-Only) ────────────────
 
     [Category("4 - Tools")]

docs/Bestandsaufnahme-2026-07.md

@@ -532,11 +532,14 @@ Siehe K3.
 5. S3 API-Key-Leak
 
 **Kurzfristig — größter Nutzen pro Aufwand**
-6. T1 Prompt-Caching
+6. ~~T1 Prompt-Caching~~ ✅ umgesetzt (inkl. T9 `cached_tokens`)
-7. T2 Tool-Ergebnisse kappen (= B5)
+7. ~~T2 Tool-Ergebnisse kappen (= B5)~~ ✅ umgesetzt
-8. T3 Günstiges Compaction-Modell
+8. ~~T3 Günstiges Compaction-Modell~~ ✅ umgesetzt
-9. B4 Kostenerfassung korrigieren
+9. ~~B4 Kostenerfassung korrigieren~~ ✅ teilweise: Prompt/Completion werden jetzt
+   getrennt erfasst statt 50/50 geschätzt. Offen bleibt die veraltete, hartcodierte
+   Preistabelle (`ModelPricing`) — Preise sollten vom `/models`-Endpoint kommen.
 10. B12 Retry/Backoff
+11. T4 Proaktiv statt reaktiv kompaktieren
 
 **Mittelfristig — Fundament**
 11. S1 DatabaseTool absichern

frm_main.cs

@@ -289,7 +289,10 @@ public partial class frm_main : Form
     /// </summary>
     private void OnEngineRunCompleted(string model, AgentRunResult result)
     {
-        _statusService?.RecordUsage(model, result.TokensUsed / 2, result.TokensUsed / 2);
+        // Echte Aufteilung statt 50/50: In Agenten-Loops liegt das Verhältnis eher bei
+        // 95:5, und da Ausgabe-Tokens ein Vielfaches kosten, war die alte Schätzung
+        // um ein Mehrfaches daneben.
+        _statusService?.RecordUsage(model, result.PromptTokens, result.CompletionTokens);
 
         if (IsDisposed || !IsHandleCreated) return;
         BeginInvoke(() =>

src/ClawdDotNet.Core/Api/Models/ChatMessage.cs

@@ -1,24 +1,33 @@
+using System.Text.Json;
 using System.Text.Json.Serialization;
 
 namespace ClawdDotNet.Core.Api.Models;
 
+[JsonConverter(typeof(ChatMessageConverter))]
 public sealed class ChatMessage
 {
-    [JsonPropertyName("role")]
     public string Role { get; set; } = "";
 
-    [JsonPropertyName("content")]
-    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     public string? Content { get; set; }
 
-    [JsonPropertyName("tool_calls")]
-    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     public List<ToolCall>? ToolCalls { get; set; }
 
-    [JsonPropertyName("tool_call_id")]
-    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
     public string? ToolCallId { get; set; }
 
+    /// <summary>
+    /// Setzt einen Prompt-Caching-Breakpoint auf diese Nachricht.
+    ///
+    /// Alles, was im Prompt VOR dem Breakpoint steht (Tool-Definitionen, System-Prompt,
+    /// vorherige Nachrichten), wird beim nächsten Aufruf aus dem Cache gelesen und
+    /// kostet nur einen Bruchteil. Der Inhalt wird dann als Block-Array statt als
+    /// einfacher String serialisiert.
+    ///
+    /// Wichtig: Der Prompt-Abschnitt vor dem Breakpoint muss zwischen zwei Aufrufen
+    /// zeichengenau identisch sein, sonst greift der Cache nicht.
+    /// </summary>
+    [JsonIgnore]
+    public bool CacheBreakpoint { get; set; }
+
     public static ChatMessage System(string content) => new() { Role = "system", Content = content };
     public static ChatMessage User(string content) => new() { Role = "user", Content = content };
     public static ChatMessage Assistant(string content) => new() { Role = "assistant", Content = content };
@@ -36,3 +45,136 @@ public sealed class ChatMessage
         Content = content
     };
 }
+
+/// <summary>
+/// Serialisiert <see cref="ChatMessage"/>. Der Inhalt geht normalerweise als einfacher
+/// String raus; ist ein <see cref="ChatMessage.CacheBreakpoint"/> gesetzt, stattdessen
+/// als Block-Array mit cache_control — das Format, das Anbieter für Prompt-Caching
+/// erwarten.
+///
+/// Beim Lesen werden beide Formate akzeptiert: Antworten liefern den Inhalt als String,
+/// gespeicherte Kontexte können ihn als Array enthalten.
+/// </summary>
+public sealed class ChatMessageConverter : JsonConverter<ChatMessage>
+{
+    public override ChatMessage Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+    {
+        if (reader.TokenType != JsonTokenType.StartObject)
+            throw new JsonException("ChatMessage: Objekt erwartet.");
+
+        var message = new ChatMessage();
+
+        while (reader.Read())
+        {
+            if (reader.TokenType == JsonTokenType.EndObject)
+                return message;
+
+            if (reader.TokenType != JsonTokenType.PropertyName)
+                continue;
+
+            var propertyName = reader.GetString();
+            reader.Read();
+
+            switch (propertyName)
+            {
+                case "role":
+                    message.Role = reader.GetString() ?? "";
+                    break;
+
+                case "content":
+                    message.Content = ReadContent(ref reader);
+                    break;
+
+                case "tool_calls":
+                    message.ToolCalls = reader.TokenType == JsonTokenType.Null
+                        ? null
+                        : JsonSerializer.Deserialize<List<ToolCall>>(ref reader, options);
+                    break;
+
+                case "tool_call_id":
+                    message.ToolCallId = reader.GetString();
+                    break;
+
+                default:
+                    reader.Skip();
+                    break;
+            }
+        }
+
+        throw new JsonException("ChatMessage: unerwartetes Ende.");
+    }
+
+    /// <summary>Nimmt den Inhalt als String oder als Block-Array entgegen.</summary>
+    private static string? ReadContent(ref Utf8JsonReader reader)
+    {
+        if (reader.TokenType == JsonTokenType.Null)
+            return null;
+
+        if (reader.TokenType == JsonTokenType.String)
+            return reader.GetString();
+
+        if (reader.TokenType != JsonTokenType.StartArray)
+        {
+            reader.Skip();
+            return null;
+        }
+
+        // Block-Array: die text-Anteile zusammenführen.
+        var parts = new List<string>();
+        while (reader.Read() && reader.TokenType != JsonTokenType.EndArray)
+        {
+            if (reader.TokenType != JsonTokenType.StartObject)
+            {
+                reader.Skip();
+                continue;
+            }
+
+            using var block = JsonDocument.ParseValue(ref reader);
+            if (block.RootElement.TryGetProperty("text", out var text) &&
+                text.GetString() is { } value)
+            {
+                parts.Add(value);
+            }
+        }
+
+        return parts.Count > 0 ? string.Join("", parts) : null;
+    }
+
+    public override void Write(Utf8JsonWriter writer, ChatMessage value, JsonSerializerOptions options)
+    {
+        writer.WriteStartObject();
+        writer.WriteString("role", value.Role);
+
+        if (value.Content is not null)
+        {
+            if (value.CacheBreakpoint)
+            {
+                // [{ "type": "text", "text": "…", "cache_control": { "type": "ephemeral" } }]
+                writer.WriteStartArray("content");
+                writer.WriteStartObject();
+                writer.WriteString("type", "text");
+                writer.WriteString("text", value.Content);
+                writer.WriteStartObject("cache_control");
+                writer.WriteString("type", "ephemeral");
+                writer.WriteEndObject();
+                writer.WriteEndObject();
+                writer.WriteEndArray();
+            }
+            else
+            {
+                writer.WriteString("content", value.Content);
+            }
+        }
+
+        if (value.ToolCalls is { Count: > 0 })
+        {
+            writer.WritePropertyName("tool_calls");
+            JsonSerializer.Serialize(writer, value.ToolCalls, options);
+        }
+
+        if (value.ToolCallId is not null)
+            writer.WriteString("tool_call_id", value.ToolCallId);
+
+        writer.WriteEndObject();
+    }
+}

src/ClawdDotNet.Core/Api/Models/ChatResponse.cs

@@ -42,6 +42,23 @@ public sealed class Usage
 
     [JsonPropertyName("total_tokens")]
     public int TotalTokens { get; set; }
+
+    [JsonPropertyName("prompt_tokens_details")]
+    public PromptTokensDetails? PromptTokensDetails { get; set; }
+
+    /// <summary>
+    /// Anteil der Prompt-Tokens, der aus dem Cache gelesen wurde. Nur damit lässt sich
+    /// belegen, ob das Prompt-Caching tatsächlich greift — ein still wirkungsloser
+    /// Cache wäre sonst nicht zu bemerken.
+    /// </summary>
+    [JsonIgnore]
+    public int CachedTokens => PromptTokensDetails?.CachedTokens ?? 0;
+}
+
+public sealed class PromptTokensDetails
+{
+    [JsonPropertyName("cached_tokens")]
+    public int CachedTokens { get; set; }
 }
 
 public sealed class ApiError

src/ClawdDotNet.Core/ClawdDotNet.Core.csproj

@@ -7,6 +7,10 @@
     <RootNamespace>ClawdDotNet.Core</RootNamespace>
   </PropertyGroup>
 
+  <ItemGroup>
+    <InternalsVisibleTo Include="ClawdDotNet.Core.Tests" />
+  </ItemGroup>
+
   <ItemGroup>
     <PackageReference Include="Microsoft.Data.Sqlite" Version="10.0.8" />
     <PackageReference Include="Microsoft.Extensions.Logging" Version="10.0.8" />

src/ClawdDotNet.Core/Config/AgentConfig.cs

@@ -88,6 +88,24 @@ public sealed class AgentConfig
 
     [JsonPropertyName("loopGuard")]
     public LoopGuardConfig LoopGuard { get; set; } = new();
+
+    /// <summary>
+    /// Prompt-Caching: "auto" (Default), "on" oder "off".
+    ///
+    /// Bei "auto" wird es für Modelle aktiviert, die cache_control unterstützen.
+    /// Der Nutzen ist erheblich, weil jeder Schritt eines Runs den kompletten Prompt
+    /// erneut sendet — System-Prompt und Tool-Definitionen also dutzendfach.
+    /// </summary>
+    [JsonPropertyName("promptCaching")]
+    public string PromptCaching { get; set; } = "auto";
+
+    /// <summary>
+    /// Maximale Länge eines einzelnen Tool-Ergebnisses in Zeichen, bevor es gekürzt in
+    /// den Kontext wandert. Ohne Grenze kann ein einziger Abruf den gesamten Kontext
+    /// sprengen (ein WebFetch mit 512 KB entspricht etwa 130.000 Tokens).
+    /// </summary>
+    [JsonPropertyName("maxToolResultChars")]
+    public int MaxToolResultChars { get; set; } = 16_000;
 }
 
 public sealed class SchedulerConfig
@@ -137,6 +155,16 @@ public sealed class LoopGuardConfig
     [JsonPropertyName("compactionThreshold")]
     public double CompactionThreshold { get; set; } = 0.80;
 
+    /// <summary>
+    /// Modell für die Zusammenfassung beim Kompaktieren. Leer = Modell des Agenten.
+    ///
+    /// Zusammenfassen ist eine anspruchslose Aufgabe; sie mit einem teuren Modell zu
+    /// erledigen kostet leicht mehr als der halbe Run, weil bis zu 30.000 Zeichen
+    /// verarbeitet werden.
+    /// </summary>
+    [JsonPropertyName("summaryModel")]
+    public string SummaryModel { get; set; } = "google/gemini-2.5-flash";
+
     [JsonIgnore]
     public TimeSpan Timeout => TimeSpan.FromSeconds(TimeoutSeconds);
 }

src/ClawdDotNet.Core/Engine/AgentEngine.cs

@@ -109,13 +109,17 @@ public sealed class AgentEngine : IAgentMessageRouter
             messages.Add(ChatMessage.User(userMessage));
 
             string? finalMessage = null;
-            var totalTokens = 0;
+            var tally = new TokenTally();
+            var cachingEnabled = PromptCache.IsEnabledFor(agentConfig.PromptCaching, agentConfig.Model);
 
             while (true)
             {
                 ct.ThrowIfCancellationRequested();
                 loopGuard.RecordStep();
 
+                if (cachingEnabled)
+                    PromptCache.ApplyBreakpoints(messages);
+
                 var request = new ChatRequest
                 {
                     Model = agentConfig.Model,
@@ -128,7 +132,7 @@ public sealed class AgentEngine : IAgentMessageRouter
                 var promptTokens = 0;
                 if (response.Usage is not null)
                 {
-                    totalTokens += response.Usage.TotalTokens;
+                    tally.Add(response.Usage);
                     promptTokens = response.Usage.PromptTokens;
                     loopGuard.RecordTokens(response.Usage.TotalTokens);
                 }
@@ -174,16 +178,21 @@ public sealed class AgentEngine : IAgentMessageRouter
 
             sw.Stop();
             logger.LogInformation(
-                "Agent run completed: {AgentId}, steps={Steps}, tokens={Tokens}, duration={Duration}ms",
+                "Agent run completed: {AgentId}, steps={Steps}, tokens={Tokens} (davon {Cached} aus Cache), duration={Duration}ms",
-                agentConfig.AgentId, loopGuard.Steps, totalTokens, sw.ElapsedMilliseconds);
+                agentConfig.AgentId, loopGuard.Steps, tally.Total, tally.Cached, sw.ElapsedMilliseconds);
 
             var result = new AgentRunResult(
                 agentConfig.AgentId,
                 AgentRunStatus.Completed,
                 finalMessage,
                 loopGuard.Steps,
-                totalTokens,
+                tally.Total,
-                sw.Elapsed);
+                sw.Elapsed)
+            {
+                PromptTokens = tally.Prompt,
+                CompletionTokens = tally.Completion,
+                CachedTokens = tally.Cached
+            };
             OnRunCompleted?.Invoke(agentConfig.Model, result);
             return result;
         }
@@ -318,13 +327,17 @@ public sealed class AgentEngine : IAgentMessageRouter
             AddChatEntry(agentConfig.AgentId, "user", userMessage, source);
 
             string? finalMessage = null;
-            var totalTokens = 0;
+            var tally = new TokenTally();
+            var cachingEnabled = PromptCache.IsEnabledFor(agentConfig.PromptCaching, agentConfig.Model);
 
             while (true)
             {
                 ct.ThrowIfCancellationRequested();
                 loopGuard.RecordStep();
 
+                if (cachingEnabled)
+                    PromptCache.ApplyBreakpoints(messages);
+
                 var request = new ChatRequest
                 {
                     Model = agentConfig.Model,
@@ -337,7 +350,7 @@ public sealed class AgentEngine : IAgentMessageRouter
                 var promptTokens = 0;
                 if (response.Usage is not null)
                 {
-                    totalTokens += response.Usage.TotalTokens;
+                    tally.Add(response.Usage);
                     promptTokens = response.Usage.PromptTokens;
                     loopGuard.RecordTokens(response.Usage.TotalTokens);
                 }
@@ -386,7 +399,12 @@ public sealed class AgentEngine : IAgentMessageRouter
             sw.Stop();
             var result = new AgentRunResult(
                 agentConfig.AgentId, AgentRunStatus.Completed, finalMessage,
-                loopGuard.Steps, totalTokens, sw.Elapsed);
+                loopGuard.Steps, tally.Total, sw.Elapsed)
+            {
+                PromptTokens = tally.Prompt,
+                CompletionTokens = tally.Completion,
+                CachedTokens = tally.Cached
+            };
             OnRunCompleted?.Invoke(agentConfig.Model, result);
             return result;
         }
@@ -786,9 +804,18 @@ public sealed class AgentEngine : IAgentMessageRouter
 
             logger.LogDebug("Tool {Tool} completed: success={Success}", toolName, result.Success);
 
-            return result.Success
+            if (!result.Success)
-                ? result.Content
+                return JsonSerializer.Serialize(new { error = result.ErrorMessage });
-                : JsonSerializer.Serialize(new { error = result.ErrorMessage });
+
+            var content = TruncateToolResult(result.Content, agentConfig.MaxToolResultChars);
+            if (content.Length != result.Content.Length)
+            {
+                logger.LogInformation(
+                    "Tool-Ergebnis von {Tool} gekürzt: {Original} → {Limit} Zeichen",
+                    toolName, result.Content.Length, agentConfig.MaxToolResultChars);
+            }
+
+            return content;
         }
         catch (ToolAccessDeniedException ex)
         {
@@ -808,6 +835,42 @@ public sealed class AgentEngine : IAgentMessageRouter
         }
     }
 
+    /// <summary>Sammelt die Token-Zahlen über alle Schritte eines Runs.</summary>
+    private sealed class TokenTally
+    {
+        public int Total { get; private set; }
+        public int Prompt { get; private set; }
+        public int Completion { get; private set; }
+        public int Cached { get; private set; }
+
+        public void Add(Usage usage)
+        {
+            Total += usage.TotalTokens;
+            Prompt += usage.PromptTokens;
+            Completion += usage.CompletionTokens;
+            Cached += usage.CachedTokens;
+        }
+    }
+
+    /// <summary>
+    /// Kürzt ein Tool-Ergebnis, bevor es in den Kontext wandert.
+    ///
+    /// Ohne diese Grenze kann ein einzelner Aufruf den Kontext sprengen — ein WebFetch
+    /// mit dem Standardlimit von 512 KB entspricht rund 130.000 Tokens in EINER
+    /// Tool-Antwort. Die Compaction greift erst danach, der teure Request ist zu dem
+    /// Zeitpunkt längst bezahlt.
+    /// </summary>
+    internal static string TruncateToolResult(string result, int maxChars)
+    {
+        if (maxChars <= 0 || result.Length <= maxChars)
+            return result;
+
+        var omitted = result.Length - maxChars;
+        return result[..maxChars] +
+               $"\n\n[… {omitted:N0} Zeichen gekürzt. Das Ergebnis war zu groß für den Kontext. " +
+               "Grenze die Abfrage ein, wenn du den Rest brauchst.]";
+    }
+
     private static List<ToolDefinition> BuildToolDefinitions(IReadOnlyList<IAgentTool> tools)
     {
         return tools.Select(t => new ToolDefinition

src/ClawdDotNet.Core/Engine/AgentRunResult.cs

@@ -8,7 +8,20 @@ public sealed record AgentRunResult(
     int TokensUsed,
     TimeSpan Duration,
     Exception? Error = null
-);
+)
+{
+    /// <summary>Summe der Eingabe-Tokens über alle Schritte des Runs.</summary>
+    public int PromptTokens { get; init; }
+
+    /// <summary>Summe der Ausgabe-Tokens über alle Schritte des Runs.</summary>
+    public int CompletionTokens { get; init; }
+
+    /// <summary>
+    /// Anteil der Eingabe-Tokens, der aus dem Prompt-Cache kam. Diese Tokens sind bereits
+    /// in <see cref="PromptTokens"/> enthalten, kosten aber nur einen Bruchteil.
+    /// </summary>
+    public int CachedTokens { get; init; }
+}
 
 public enum AgentRunStatus
 {

src/ClawdDotNet.Core/Engine/ContextCompactor.cs

@@ -69,8 +69,12 @@ public sealed class ContextCompactor
                 return true;
         }
 
-        // Stufe 2: Auto-Compaction via LLM
+        // Stufe 2: Auto-Compaction via LLM — bewusst mit dem günstigen Modell.
-        await CompactViaLlmAsync(messages, model, ct);
+        var summaryModel = string.IsNullOrWhiteSpace(guard.SummaryModel)
+            ? model
+            : guard.SummaryModel;
+
+        await CompactViaLlmAsync(messages, summaryModel, ct);
         return true;
     }
 

src/ClawdDotNet.Core/Engine/PromptCache.cs

@@ -0,0 +1,67 @@
+using ClawdDotNet.Core.Api.Models;
+
+namespace ClawdDotNet.Core.Engine;
+
+/// <summary>
+/// Setzt Prompt-Caching-Breakpoints in die Nachrichtenliste.
+///
+/// Hintergrund: In einem Agenten-Run wird bei JEDEM Schritt der komplette Prompt erneut
+/// gesendet und voll berechnet — inklusive Tool-Definitionen und System-Prompt, die sich
+/// nie ändern. Bei zehn Schritten und einem 15k-Präfix sind das 150.000 Eingabe-Tokens
+/// statt 15.000.
+///
+/// Ein Breakpoint markiert das Ende eines stabilen Prompt-Abschnitts. Alles davor wird
+/// beim nächsten Aufruf aus dem Cache gelesen und kostet nur einen Bruchteil.
+///
+/// Zwei Breakpoints werden gesetzt:
+/// 1. auf den System-Prompt — deckt Tool-Definitionen und System-Prompt ab,
+/// 2. rollierend auf die letzte Nachricht — deckt den bereits gelaufenen Gesprächsverlauf ab.
+/// </summary>
+public static class PromptCache
+{
+    /// <summary>
+    /// Modelle, bei denen "auto" das Caching einschaltet. Andere Anbieter ignorieren
+    /// cache_control entweder oder cachen ohnehin automatisch.
+    /// </summary>
+    private static readonly string[] AutoEnabledPrefixes = ["anthropic/"];
+
+    public static bool IsEnabledFor(string setting, string model) => setting?.ToLowerInvariant() switch
+    {
+        "on" => true,
+        "off" => false,
+        _ => AutoEnabledPrefixes.Any(p => model.StartsWith(p, StringComparison.OrdinalIgnoreCase))
+    };
+
+    /// <summary>
+    /// Setzt die Breakpoints neu. Vorherige werden entfernt, damit sich pro Schritt
+    /// nie mehr als die beabsichtigten Markierungen ansammeln.
+    /// </summary>
+    public static void ApplyBreakpoints(List<ChatMessage> messages)
+    {
+        foreach (var msg in messages)
+            msg.CacheBreakpoint = false;
+
+        if (messages.Count == 0)
+            return;
+
+        // 1. System-Prompt — der stabilste Teil überhaupt.
+        var system = messages[0].Role == "system" ? messages[0] : null;
+        if (system?.Content is not null)
+            system.CacheBreakpoint = true;
+
+        // 2. Letzte Nachricht mit Inhalt. Beim nächsten Schritt ist alles bis hierher
+        //    unverändert und wird aus dem Cache gelesen.
+        //    Eine assistant-Nachricht mit tool_calls hat keinen Textinhalt und kann
+        //    deshalb keinen Block tragen — in dem Fall bleibt es beim System-Breakpoint.
+        for (var i = messages.Count - 1; i >= 1; i--)
+        {
+            if (messages[i].Content is null)
+                continue;
+
+            if (!ReferenceEquals(messages[i], system))
+                messages[i].CacheBreakpoint = true;
+
+            break;
+        }
+    }
+}

src/ClawdDotNet.Tools.AgentEditor/AgentEditorTool.cs

@@ -326,13 +326,16 @@ public sealed class AgentEditorTool : IAgentTool
             tools = new Dictionary<string, object>(),
             scheduler = (object?)null,
             toolJobs = Array.Empty<object>(),
+            promptCaching = "auto",
+            maxToolResultChars = 16000,
             loopGuard = new
             {
                 maxSteps = 20,
                 maxCumulativeTokens = 500000,
                 timeoutSeconds = 600,
                 maxContextTokens = 100000,
-                compactionThreshold = 0.8
+                compactionThreshold = 0.8,
+                summaryModel = "google/gemini-2.5-flash"
             }
         };
         await File.WriteAllTextAsync(

tests/ClawdDotNet.Core.Tests/Api/ChatMessageSerializationTests.cs

@@ -0,0 +1,149 @@
+using System.Text.Json;
+using ClawdDotNet.Core.Api.Models;
+using Shouldly;
+
+namespace ClawdDotNet.Core.Tests.Api;
+
+public sealed class ChatMessageSerializationTests
+{
+    private static string Serialize(ChatMessage m) => JsonSerializer.Serialize(m);
+    private static ChatMessage Deserialize(string json) => JsonSerializer.Deserialize<ChatMessage>(json)!;
+
+    // ═══════════════════════════════════════════════════════════
+    //  Standardformat
+    // ═══════════════════════════════════════════════════════════
+
+    [Fact]
+    public void Ohne_Breakpoint_bleibt_der_Inhalt_ein_einfacher_String()
+    {
+        var json = Serialize(ChatMessage.User("Hallo"));
+
+        json.ShouldBe("""{"role":"user","content":"Hallo"}""");
+    }
+
+    [Fact]
+    public void Nullwerte_werden_weggelassen()
+    {
+        var json = Serialize(ChatMessage.Assistant("Antwort"));
+
+        json.ShouldNotContain("tool_calls");
+        json.ShouldNotContain("tool_call_id");
+    }
+
+    [Fact]
+    public void ToolAntwort_traegt_ihre_ToolCallId()
+    {
+        var json = Serialize(ChatMessage.ToolResponse("call_42", "Ergebnis"));
+
+        json.ShouldBe("""{"role":"tool","content":"Ergebnis","tool_call_id":"call_42"}""");
+    }
+
+    [Fact]
+    public void AssistantMitToolCalls_serialisiert_die_Aufrufe()
+    {
+        var msg = ChatMessage.AssistantWithToolCalls([
+            new ToolCall { Id = "c1", Function = new ToolCallFunction { Name = "FileRW", Arguments = "{}" } }
+        ]);
+
+        var json = Serialize(msg);
+
+        json.ShouldContain("tool_calls");
+        json.ShouldContain("FileRW");
+        json.ShouldNotContain("\"content\"", Case.Sensitive);
+    }
+
+    // ═══════════════════════════════════════════════════════════
+    //  Cache-Breakpoint
+    // ═══════════════════════════════════════════════════════════
+
+    [Fact]
+    public void Mit_Breakpoint_wird_der_Inhalt_zum_Block_mit_cache_control()
+    {
+        var msg = ChatMessage.System("Du bist ein Agent.");
+        msg.CacheBreakpoint = true;
+
+        var json = Serialize(msg);
+
+        json.ShouldBe(
+            """{"role":"system","content":[{"type":"text","text":"Du bist ein Agent.","cache_control":{"type":"ephemeral"}}]}""");
+    }
+
+    [Fact]
+    public void Der_Breakpoint_selbst_wird_nicht_als_Feld_serialisiert()
+    {
+        var msg = ChatMessage.User("Text");
+        msg.CacheBreakpoint = true;
+
+        Serialize(msg).ShouldNotContain("CacheBreakpoint", Case.Insensitive);
+    }
+
+    // ═══════════════════════════════════════════════════════════
+    //  Deserialisierung: beide Formate
+    // ═══════════════════════════════════════════════════════════
+
+    [Fact]
+    public void Inhalt_als_String_wird_gelesen()
+    {
+        var msg = Deserialize("""{"role":"assistant","content":"Antwort"}""");
+
+        msg.Role.ShouldBe("assistant");
+        msg.Content.ShouldBe("Antwort");
+    }
+
+    [Fact]
+    public void Inhalt_als_Blockarray_wird_gelesen()
+    {
+        // So sieht ein persistierter Kontext aus, der mit Breakpoint geschrieben wurde.
+        var msg = Deserialize(
+            """{"role":"system","content":[{"type":"text","text":"Prompt","cache_control":{"type":"ephemeral"}}]}""");
+
+        msg.Content.ShouldBe("Prompt");
+    }
+
+    [Fact]
+    public void Mehrere_Textbloecke_werden_zusammengefuehrt()
+    {
+        var msg = Deserialize(
+            """{"role":"user","content":[{"type":"text","text":"Teil A"},{"type":"text","text":" Teil B"}]}""");
+
+        msg.Content.ShouldBe("Teil A Teil B");
+    }
+
+    [Fact]
+    public void Fehlender_Inhalt_wird_zu_null()
+    {
+        var msg = Deserialize("""{"role":"assistant","tool_calls":[]}""");
+
+        msg.Content.ShouldBeNull();
+    }
+
+    [Fact]
+    public void Unbekannte_Felder_stoeren_nicht()
+    {
+        var msg = Deserialize("""{"role":"user","content":"Text","reasoning":"…","annotations":[1,2]}""");
+
+        msg.Content.ShouldBe("Text");
+    }
+
+    [Fact]
+    public void RoundTrip_erhaelt_alle_Felder()
+    {
+        var original = ChatMessage.ToolResponse("call_7", "Das Ergebnis");
+
+        var restored = Deserialize(Serialize(original));
+
+        restored.Role.ShouldBe("tool");
+        restored.Content.ShouldBe("Das Ergebnis");
+        restored.ToolCallId.ShouldBe("call_7");
+    }
+
+    [Fact]
+    public void RoundTrip_erhaelt_Umlaute_und_Emoji()
+    {
+        var original = ChatMessage.User("Grüße aus München 🦀 — größer & schöner");
+
+        var restored = Deserialize(Serialize(original));
+
+        restored.Content.ShouldBe("Grüße aus München 🦀 — größer & schöner");
+    }
+}

tests/ClawdDotNet.Core.Tests/Engine/PromptCacheTests.cs

@@ -0,0 +1,159 @@
+using System.Text.Json;
+using ClawdDotNet.Core.Api.Models;
+using ClawdDotNet.Core.Engine;
+using ClawdDotNet.Core.Tests.Infrastructure;
+using Shouldly;
+
+namespace ClawdDotNet.Core.Tests.Engine;
+
+public sealed class PromptCacheTests
+{
+    // ═══════════════════════════════════════════════════════════
+    //  Aktivierung
+    // ═══════════════════════════════════════════════════════════
+
+    [Theory]
+    [InlineData("auto", "anthropic/claude-sonnet-4-5", true)]
+    [InlineData("auto", "anthropic/claude-haiku-4.5", true)]
+    [InlineData("auto", "openai/gpt-4o", false)]
+    [InlineData("auto", "google/gemini-2.5-flash", false)]
+    [InlineData("on", "openai/gpt-4o", true)]
+    [InlineData("off", "anthropic/claude-sonnet-4-5", false)]
+    [InlineData("OFF", "anthropic/claude-sonnet-4-5", false)]
+    public void Aktivierung_richtet_sich_nach_Einstellung_und_Modell(string setting, string model, bool expected)
+    {
+        PromptCache.IsEnabledFor(setting, model).ShouldBe(expected);
+    }
+
+    // ═══════════════════════════════════════════════════════════
+    //  Platzierung der Breakpoints
+    // ═══════════════════════════════════════════════════════════
+
+    [Fact]
+    public void Der_SystemPrompt_bekommt_einen_Breakpoint()
+    {
+        var messages = Conversation.Start("System").User("Frage").Build();
+
+        PromptCache.ApplyBreakpoints(messages);
+
+        messages[0].Role.ShouldBe("system");
+        messages[0].CacheBreakpoint.ShouldBeTrue();
+    }
+
+    [Fact]
+    public void Die_letzte_Nachricht_mit_Inhalt_bekommt_einen_rollierenden_Breakpoint()
+    {
+        var messages = Conversation.Start().User("A").Assistant("B").User("C").Build();
+
+        PromptCache.ApplyBreakpoints(messages);
+
+        messages[^1].CacheBreakpoint.ShouldBeTrue();
+        messages[^1].Content.ShouldBe("C");
+    }
+
+    [Fact]
+    public void Eine_AssistantNachricht_ohne_Inhalt_traegt_keinen_Breakpoint()
+    {
+        // assistant mit tool_calls hat keinen Textinhalt und kann keinen Block tragen.
+        var messages = Conversation.Start().User("A").Build();
+        messages.Add(ChatMessage.AssistantWithToolCalls([
+            new ToolCall { Id = "c1", Function = new ToolCallFunction { Name = "T", Arguments = "{}" } }
+        ]));
+
+        PromptCache.ApplyBreakpoints(messages);
+
+        messages[^1].CacheBreakpoint.ShouldBeFalse();
+        messages.Count(m => m.CacheBreakpoint).ShouldBeGreaterThan(0, "der System-Breakpoint muss bleiben");
+    }
+
+    [Fact]
+    public void Es_werden_hoechstens_zwei_Breakpoints_gesetzt()
+    {
+        // Anbieter erlauben nur eine begrenzte Zahl — sie dürfen sich nicht ansammeln.
+        var messages = Conversation.Start().Repeat(10).Build();
+
+        PromptCache.ApplyBreakpoints(messages);
+
+        messages.Count(m => m.CacheBreakpoint).ShouldBeLessThanOrEqualTo(2);
+    }
+
+    [Fact]
+    public void Wiederholtes_Anwenden_sammelt_keine_Breakpoints_an()
+    {
+        var messages = Conversation.Start().Repeat(3).Build();
+
+        PromptCache.ApplyBreakpoints(messages);
+        messages.Add(ChatMessage.User("Noch eine Frage"));
+        PromptCache.ApplyBreakpoints(messages);
+        messages.Add(ChatMessage.User("Und noch eine"));
+        PromptCache.ApplyBreakpoints(messages);
+
+        messages.Count(m => m.CacheBreakpoint).ShouldBeLessThanOrEqualTo(2);
+        messages[^1].CacheBreakpoint.ShouldBeTrue("der Breakpoint muss mitwandern");
+    }
+
+    [Fact]
+    public void Eine_leere_Liste_fuehrt_nicht_zu_einem_Fehler()
+    {
+        var messages = new List<ChatMessage>();
+
+        Should.NotThrow(() => PromptCache.ApplyBreakpoints(messages));
+    }
+
+    // ═══════════════════════════════════════════════════════════
+    //  Präfix-Stabilität — der entscheidende Test
+    // ═══════════════════════════════════════════════════════════
+
+    /// <summary>
+    /// Der gecachte Prompt-Abschnitt muss zwischen zwei Schritten zeichengenau identisch
+    /// sein. Ein einziger Zeitstempel im System-Prompt würde den Cache bei jedem Schritt
+    /// verwerfen — die Kosten blieben unverändert, ohne dass es irgendwo auffiele.
+    /// Genau davor schützt dieser Test.
+    /// </summary>
+    [Fact]
+    public async Task Der_Praefix_bleibt_ueber_alle_Schritte_zeichengleich()
+    {
+        var fixture = new EngineFixture().WithTool(FakeTool.Returning("ok"));
+        var agent = fixture.AddAgent("agent-cache", "TestTool");
+        agent.Model = "anthropic/claude-sonnet-4-5";
+        agent.PromptCaching = "on";
+
+        // Acht Tool-Schritte, dann eine Textantwort.
+        for (var i = 0; i < 8; i++)
+            fixture.Client.RespondsWithToolCall("TestTool");
+        fixture.Client.RespondsWithText("Fertig");
+
+        await fixture.Engine.ChatAsync(agent, "Los", "test-instance", default);
+
+        fixture.Client.ReceivedRequests.Count.ShouldBe(9);
+
+        // Die system-Nachricht ist der stabile Präfix — sie muss in jedem Request
+        // byte-identisch serialisiert werden.
+        var systemPayloads = fixture.Client.ReceivedRequests
+            .Select(r => JsonSerializer.Serialize(r.Messages[0]))
+            .Distinct()
+            .ToList();
+
+        systemPayloads.Count.ShouldBe(1,
+            "der System-Prompt muss über alle Schritte hinweg identisch serialisiert werden:\n" +
+            string.Join("\n", systemPayloads));
+
+        systemPayloads[0].ShouldContain("cache_control");
+    }
+
+    [Fact]
+    public async Task Ohne_Caching_enthaelt_der_Request_kein_cache_control()
+    {
+        var fixture = new EngineFixture().WithTool(FakeTool.Returning("ok"));
+        var agent = fixture.AddAgent("agent-nocache", "TestTool");
+        agent.Model = "openai/gpt-4o";
+        agent.PromptCaching = "auto";      // bei diesem Modell also aus
+
+        fixture.Client.RespondsWithText("Fertig");
+
+        await fixture.Engine.ChatAsync(agent, "Los", "test-instance", default);
+
+        var json = JsonSerializer.Serialize(fixture.Client.ReceivedRequests[0].Messages);
+        json.ShouldNotContain("cache_control");
+    }
+}

tests/ClawdDotNet.Core.Tests/Engine/TokenAccountingTests.cs

@@ -0,0 +1,161 @@
+using ClawdDotNet.Core.Api.Models;
+using ClawdDotNet.Core.Config;
+using ClawdDotNet.Core.Engine;
+using ClawdDotNet.Core.Tests.Infrastructure;
+using Shouldly;
+
+namespace ClawdDotNet.Core.Tests.Engine;
+
+public sealed class TokenAccountingTests
+{
+    // ═══════════════════════════════════════════════════════════
+    //  B4 — Prompt und Completion getrennt erfassen
+    // ═══════════════════════════════════════════════════════════
+
+    [Fact]
+    public async Task Prompt_und_Completion_werden_getrennt_aufsummiert()
+    {
+        // Bisher schätzte die UI 50/50. Real liegt das Verhältnis eher bei 95:5 —
+        // und da Ausgabe-Tokens ein Vielfaches kosten, war die Kostenanzeige
+        // um ein Mehrfaches daneben.
+        var fixture = new EngineFixture().WithTool(FakeTool.Returning("ok"));
+        var agent = fixture.AddAgent("agent-tokens", "TestTool");
+
+        fixture.Client
+            .RespondsWithText("Fertig", new Usage
+            {
+                PromptTokens = 9_500,
+                CompletionTokens = 500,
+                TotalTokens = 10_000
+            });
+
+        var result = await fixture.Engine.ChatAsync(agent, "Frage", "test-instance", default);
+
+        result.PromptTokens.ShouldBe(9_500);
+        result.CompletionTokens.ShouldBe(500);
+        result.TokensUsed.ShouldBe(10_000);
+    }
+
+    [Fact]
+    public async Task Ueber_mehrere_Schritte_wird_korrekt_summiert()
+    {
+        var fixture = new EngineFixture().WithTool(FakeTool.Returning("ok"));
+        var agent = fixture.AddAgent("agent-sum", "TestTool");
+
+        fixture.Client
+            .RespondsWithToolCall("TestTool")        // 100 / 20 / 120 laut Fake
+            .RespondsWithToolCall("TestTool")
+            .RespondsWithText("Fertig");
+
+        var result = await fixture.Engine.ChatAsync(agent, "Frage", "test-instance", default);
+
+        result.StepCount.ShouldBe(3);
+        result.PromptTokens.ShouldBe(300);
+        result.CompletionTokens.ShouldBe(60);
+        result.TokensUsed.ShouldBe(360);
+    }
+
+    // ═══════════════════════════════════════════════════════════
+    //  T9 — Cache-Wirkung messbar machen
+    // ═══════════════════════════════════════════════════════════
+
+    [Fact]
+    public async Task Gecachte_Tokens_werden_durchgereicht()
+    {
+        // Ohne diese Zahl liesse sich nicht belegen, ob das Prompt-Caching greift —
+        // ein still wirkungsloser Cache wäre sonst nicht zu bemerken.
+        var fixture = new EngineFixture();
+        var agent = fixture.AddAgent("agent-cached");
+
+        fixture.Client.RespondsWithText("Fertig", new Usage
+        {
+            PromptTokens = 20_000,
+            CompletionTokens = 300,
+            TotalTokens = 20_300,
+            PromptTokensDetails = new PromptTokensDetails { CachedTokens = 18_000 }
+        });
+
+        var result = await fixture.Engine.ChatAsync(agent, "Frage", "test-instance", default);
+
+        result.CachedTokens.ShouldBe(18_000);
+    }
+
+    [Fact]
+    public void Fehlende_Cache_Angaben_ergeben_null_statt_eines_Fehlers()
+    {
+        var usage = new Usage { PromptTokens = 100, CompletionTokens = 10, TotalTokens = 110 };
+
+        usage.CachedTokens.ShouldBe(0);
+    }
+
+    // ═══════════════════════════════════════════════════════════
+    //  T3 — Compaction läuft mit dem günstigen Modell
+    // ═══════════════════════════════════════════════════════════
+
+    [Fact]
+    public async Task Die_Zusammenfassung_nutzt_das_guenstige_Modell()
+    {
+        var client = new FakeChatClient().AlwaysRespondsWithText("- Zusammenfassung.");
+        var compactor = new ContextCompactor(client, TestLogging.Factory);
+
+        var guard = new LoopGuardConfig
+        {
+            MaxContextTokens = 1_000,
+            CompactionThreshold = 0.5,
+            SummaryModel = "google/gemini-2.5-flash"
+        };
+
+        var messages = Conversation.Start().Repeat(10).Build();
+
+        await compactor.CompactIfNeededAsync(messages, 50_000, guard, "anthropic/claude-opus-4", default);
+
+        client.ReceivedRequests.ShouldNotBeEmpty();
+        client.ReceivedRequests[0].Model.ShouldBe("google/gemini-2.5-flash",
+            "Zusammenfassen ist anspruchslos und darf nicht das teure Agentenmodell belegen");
+    }
+
+    [Fact]
+    public async Task Ohne_konfiguriertes_SummaryModel_wird_das_Agentenmodell_verwendet()
+    {
+        var client = new FakeChatClient().AlwaysRespondsWithText("- Zusammenfassung.");
+        var compactor = new ContextCompactor(client, TestLogging.Factory);
+
+        var guard = new LoopGuardConfig
+        {
+            MaxContextTokens = 1_000,
+            CompactionThreshold = 0.5,
+            SummaryModel = ""
+        };
+
+        var messages = Conversation.Start().Repeat(10).Build();
+
+        await compactor.CompactIfNeededAsync(messages, 50_000, guard, "anthropic/claude-opus-4", default);
+
+        client.ReceivedRequests[0].Model.ShouldBe("anthropic/claude-opus-4");
+    }
+
+    // ═══════════════════════════════════════════════════════════
+    //  Nur der wegfallende Teil wird zusammengefasst
+    // ═══════════════════════════════════════════════════════════
+
+    [Fact]
+    public async Task Der_erhaltene_Tail_geht_nicht_in_den_Zusammenfassungs_Aufruf()
+    {
+        // Der Tail bleibt wörtlich erhalten — ihn zusätzlich zusammenzufassen
+        // wäre doppelt bezahlter Kontext.
+        var client = new FakeChatClient().AlwaysRespondsWithText("- Zusammenfassung.");
+        var compactor = new ContextCompactor(client, TestLogging.Factory);
+
+        var guard = new LoopGuardConfig { MaxContextTokens = 1_000, CompactionThreshold = 0.5 };
+
+        var messages = Conversation.Start()
+            .Repeat(8)
+            .User("EINZIGARTIGE-LETZTE-NACHRICHT")
+            .Build();
+
+        await compactor.CompactIfNeededAsync(messages, 50_000, guard, "test/model", default);
+
+        var summaryPrompt = client.ReceivedRequests[0].Messages.Last().Content!;
+        summaryPrompt.ShouldNotContain("EINZIGARTIGE-LETZTE-NACHRICHT");
+    }
+}

tests/ClawdDotNet.Core.Tests/Engine/ToolResultTruncationTests.cs

@@ -0,0 +1,79 @@
+using ClawdDotNet.Core.Engine;
+using ClawdDotNet.Core.Tests.Infrastructure;
+using Shouldly;
+
+namespace ClawdDotNet.Core.Tests.Engine;
+
+/// <summary>
+/// T2 aus der Token-Analyse: Ein einzelnes Tool-Ergebnis konnte den Kontext sprengen.
+/// Ein WebFetch mit dem Standardlimit von 512 KB entspricht rund 130.000 Tokens in
+/// EINER Antwort — die Compaction greift erst danach, bezahlt ist der Request längst.
+/// </summary>
+public sealed class ToolResultTruncationTests
+{
+    [Fact]
+    public async Task Ein_riesiges_Toolergebnis_wird_gekappt_bevor_es_in_den_Kontext_geht()
+    {
+        var riesig = new string('x', 500_000);
+        var fixture = new EngineFixture().WithTool(FakeTool.Returning(riesig));
+        var agent = fixture.AddAgent("agent-trunc", "TestTool");
+        agent.MaxToolResultChars = 16_000;
+
+        fixture.Client
+            .RespondsWithToolCall("TestTool")
+            .RespondsWithText("Fertig");
+
+        await fixture.Engine.ChatAsync(agent, "Hol die Daten", "test-instance", default);
+
+        var context = fixture.Engine.GetChatContext(agent.AgentId);
+        var toolMessage = context.Single(m => m.Role == "tool");
+
+        toolMessage.Content!.Length.ShouldBeLessThan(20_000);
+        toolMessage.Content.ShouldContain("gekürzt");
+    }
+
+    [Fact]
+    public async Task Ein_kleines_Toolergebnis_bleibt_unveraendert()
+    {
+        const string klein = "Alles in Ordnung.";
+        var fixture = new EngineFixture().WithTool(FakeTool.Returning(klein));
+        var agent = fixture.AddAgent("agent-klein", "TestTool");
+
+        fixture.Client
+            .RespondsWithToolCall("TestTool")
+            .RespondsWithText("Fertig");
+
+        await fixture.Engine.ChatAsync(agent, "Prüfe", "test-instance", default);
+
+        var context = fixture.Engine.GetChatContext(agent.AgentId);
+        context.Single(m => m.Role == "tool").Content.ShouldBe(klein);
+    }
+
+    [Theory]
+    [InlineData(100, 50)]
+    [InlineData(1_000, 999)]
+    [InlineData(50_000, 16_000)]
+    public void Gekappte_Ergebnisse_nennen_die_Menge_der_entfallenen_Zeichen(int length, int limit)
+    {
+        var result = AgentEngine.TruncateToolResult(new string('a', length), limit);
+
+        result.ShouldStartWith(new string('a', limit));
+        result.ShouldContain((length - limit).ToString("N0"));
+    }
+
+    [Fact]
+    public void Ohne_Limit_wird_nicht_gekappt()
+    {
+        var original = new string('a', 100_000);
+
+        AgentEngine.TruncateToolResult(original, 0).ShouldBe(original);
+    }
+
+    [Fact]
+    public void Genau_auf_der_Grenze_wird_nicht_gekappt()
+    {
+        var original = new string('a', 1_000);
+
+        AgentEngine.TruncateToolResult(original, 1_000).ShouldBe(original);
+    }
+}

tests/ClawdDotNet.Core.Tests/Infrastructure/FakeChatClient.cs

@@ -151,6 +151,8 @@ internal sealed class FakeChatClient : IChatCompletionClient
         Role = m.Role,
         Content = m.Content,
         ToolCallId = m.ToolCallId,
+        // Muss mitkopiert werden, sonst prüfen Caching-Tests am Wire-Format vorbei.
+        CacheBreakpoint = m.CacheBreakpoint,
         ToolCalls = m.ToolCalls?.Select(tc => new ToolCall
         {
             Id = tc.Id,