micro-models-agent 0.41.0 → 0.41.2

package/dist/core/agent.js

@@ -1,15 +1,18 @@
-import { join } from "path";
 import { t } from "../i18n/index";
 import { pc } from "../ui/colors";
 import { PromptBuilder } from "./prompt-builder";
 import { processRegistry } from "../modules/processes";
 import { SessionLogger } from "./session-logger";
 import { runWithMoE } from "./agent-moe";
-import { MemoryStore } from "../modules/memory/store";
 import { StepVerifier } from "../modules/execution/verifier";
 const TOOL_RESULT_MAX_TOKENS_RATIO = 0.3;
 const TOOL_RESULT_ABSOLUTE_MAX_CHARS = 15000;
 const QUALITY_TRIGGER_THRESHOLD = 40;
+/** Minimum iterations between quality-triggered forced compactions. Without
+ * this, a low-quality context re-triggers compaction on EVERY iteration
+ * (observed: 56 compactions in ~28 min) and the compaction itself can't
+ * restore quality, so the agent burns the whole budget compacting. */
+const FORCED_COMPACTION_COOLDOWN = 3;
 /** True when the text looks like a raw JSON tool payload (garbage to display). */
 function isToolCallJson(text) {
     const trimmed = text.trim();
@@ -24,6 +27,19 @@ function isToolCallJson(text) {
     }
     return false;
 }
+/**
+ * Max chars a tool result may occupy, given remaining budget and whether
+ * the tool bounds its own output. Tools that declare `boundedOutput` (e.g.
+ * read_file with its line limit) are never truncated by the budget — a
+ * near-full context used to cut them to ~2K chars, making the model believe
+ * files were truncated and re-read them forever.
+ */
+export function toolOutputCharLimit(remainingBudget, historyBudget, bounded) {
+    if (bounded)
+        return Number.MAX_SAFE_INTEGER;
+    const maxCharsByRatio = Math.floor(historyBudget * TOOL_RESULT_MAX_TOKENS_RATIO * 2);
+    return Math.min(remainingBudget, maxCharsByRatio, TOOL_RESULT_ABSOLUTE_MAX_CHARS);
+}
 export class Agent {
     deps;
     systemPromptAdded = false;
@@ -43,8 +59,7 @@ export class Agent {
         }
     }
     buildSystemPrompt() {
-        const systemBudget = Math.floor(this.deps.config.contextWindow *
-            this.deps.config.contextBudget.systemPrompt);
+        const systemBudget = Math.floor(this.deps.config.contextWindow * this.deps.config.contextBudget.systemPrompt);
         const builder = new PromptBuilder(systemBudget);
         builder.addBlocks(this.deps.promptBlocks);
         const dynamic = this.deps.getDynamicPromptBlocks?.() ?? [];
@@ -64,7 +79,45 @@ export class Agent {
         if (pluginBlocks.length > 0) {
             builder.addBlocks(pluginBlocks);
         }
-        return builder.build();
+        const result = builder.build();
+        return {
+            prompt: result.prompt,
+            excluded: result.excluded,
+            blocks: result.blocks,
+        };
+    }
+    /**
+     * Log the current context state to the session log. Called every iteration
+     * so the session.jsonl shows a full timeline of how the context grows,
+     * compacts, and what it consists of. The `start` snapshot additionally
+     * carries the system-prompt block breakdown (which blocks, priorities,
+     * token estimates, what was excluded by the budget).
+     */
+    logContextStat(kind, iteration, slog, blocks) {
+        const cm = this.deps.contextManager;
+        if (typeof cm.getSnapshot !== "function")
+            return;
+        const snap = cm.getSnapshot();
+        const history = cm.getActiveHistory();
+        const systemMsg = history.find((m) => m.role === "system");
+        slog.logContext({
+            kind,
+            iteration,
+            window: snap.window,
+            systemBudget: snap.budget.systemPrompt,
+            reserveBudget: snap.budget.responseReserve,
+            historyBudget: snap.budget.history,
+            systemTokens: kind === "start" && systemMsg && typeof systemMsg.content === "string"
+                ? this.deps.llmProvider.countTokens(systemMsg.content)
+                : undefined,
+            toolTokens: snap.toolTokens,
+            tokens: snap.tokens,
+            quality: snap.quality,
+            messageCount: snap.messageCount,
+            compactionCount: snap.compactionCount,
+            iterationsSinceCompaction: snap.iterationsSinceCompaction,
+            blocks,
+        });
     }
     getSystemPromptInfo() {
         const { prompt, excluded } = this.buildSystemPrompt();
@@ -92,27 +145,26 @@ export class Agent {
     }
     refreshSystemPrompt() {
         const { prompt } = this.buildSystemPrompt();
-        const current = this.deps.contextManager
-            .getActiveHistory()
-            .find((m) => m.role === "system");
+        const current = this.deps.contextManager.getActiveHistory().find((m) => m.role === "system");
         if (!current || current.content !== prompt) {
             this.deps.contextManager.updateSystemPrompt?.(prompt);
         }
     }
-    truncateToolOutput(output, budget, currentTokens) {
-        const remainingBudget = budget.history - currentTokens;
-        const maxCharsByBudget = Math.floor(remainingBudget * 0.5 * 2);
-        const maxCharsByRatio = Math.floor(budget.history * TOOL_RESULT_MAX_TOKENS_RATIO * 2);
-        const maxChars = Math.min(maxCharsByBudget, maxCharsByRatio, TOOL_RESULT_ABSOLUTE_MAX_CHARS);
+    truncateToolOutput(output, budget, currentTokens, bounded) {
+        const remainingBudget = Math.max(0, budget.history - currentTokens);
+        const maxChars = toolOutputCharLimit(remainingBudget, budget.history, bounded);
         if (output.length <= maxChars)
             return output;
         const truncated = output.slice(0, maxChars);
         const removedChars = output.length - maxChars;
-        return (truncated +
-            `\n\n${t("tool.truncated", { tokens: Math.ceil(removedChars / 2) })}`);
+        return truncated + `\n\n${t("tool.truncated", { tokens: Math.ceil(removedChars / 2) })}`;
     }
     emitPhase(iteration, phase, onPhase) {
-        this.deps.pluginManager.runOnPhase?.({ iteration, logger: this.deps.logger }, phase);
+        this.deps.pluginManager.runOnPhase?.({
+            iteration,
+            logger: this.deps.logger,
+            contextManager: this.deps.contextManager,
+        }, phase);
         onPhase?.(phase);
     }
     async run(input, onChunk, onMeta, onTool, onPhase) {
@@ -125,6 +177,10 @@ export class Agent {
         }
         if (!this.systemPromptAdded &&
             !contextManager.getActiveHistory().some((m) => m.role === "system")) {
+            const lazy = this.deps.lazyPromptBlocks ? await this.deps.lazyPromptBlocks() : [];
+            if (lazy.length > 0) {
+                this.deps.promptBlocks.push(...lazy);
+            }
             const { prompt: systemPrompt, excluded } = this.buildSystemPrompt();
             contextManager.addMessage({ role: "system", content: systemPrompt });
             this.systemPromptAdded = true;
@@ -135,6 +191,7 @@ export class Agent {
             pluginManager.runOnSessionStart({
                 logger,
                 sessionManager: sessionManager?.getActiveMeta(),
+                contextManager,
             });
             if (config.session?.baselineCheck !== false) {
                 const verifier = new StepVerifier(baseDir);
@@ -149,6 +206,13 @@ export class Agent {
                     .catch(() => { });
             }
         }
+        // A new user message starts a fresh compaction interval — iterations
+        // from the previous turn must not trigger a compaction on iteration 1
+        // of this one (observed: turn 2 compacted at iteration 8, deleting the
+        // just-sent task along with 40+ old turns).
+        if (typeof contextManager.resetUserTurn === "function") {
+            contextManager.resetUserTurn();
+        }
         contextManager.addMessage({ role: "user", content: input });
         slog.logUser(input);
         if (config.moe?.enabled) {
@@ -168,6 +232,12 @@ export class Agent {
         this.abortController = new AbortController();
         let iteration = 0;
         let lastText = "";
+        // The actual most-recent model output (tool commentary, retried answers
+        // included). Repetition is compared against THIS, not the last *accepted*
+        // text — a frozen accepted answer made consecutive retries compare
+        // against a stale baseline and flag every re-answer as repetitive.
+        let lastModelText = "";
+        let lastForcedCompactionIteration = -FORCED_COMPACTION_COOLDOWN;
         let hallucinationRetries = 0;
         let lastToolSignature = "";
         let apiPromptTokens = 0;
@@ -176,21 +246,40 @@ export class Agent {
         const MAX_HALLUCINATION_RETRIES = 3;
         let consecutiveToolFailures = 0;
         const MAX_CONSECUTIVE_TOOL_FAILURES = 5;
+        // Per-tool failure counts and which tools already produced a memory rule.
+        const toolFailureCounts = new Map();
+        const memoryRuleRecorded = new Set();
+        const MIN_REPEATED_TOOL_FAILURES = 3;
         let auditRetries = 0;
         const MAX_AUDIT_RETRIES = 3;
         let emptyResponseRetries = 0;
         const MAX_EMPTY_RESPONSE_RETRIES = 2;
         let emptyResponseExhausted = false;
+        let auditFailed = false;
+        let lastAuditSummary = "";
+        // Set when the audit gate rejects a final answer and re-prompts: the next
+        // non-tool response is then a re-answer of an already-completed task, so
+        // a repetition verdict is expected and must not burn a hallucination retry.
+        let suppressRepetitionRetry = false;
         let repeatedToolCount = 0;
         const MAX_REPEATED_TOOL_CALLS = 2;
         // Account for tool definitions in context budget (they're sent via body.tools, not messages)
-        const allToolsForBudget = toolExecutor.getToolDefinitions(this.deps.toolTags);
-        const toolTokenEstimate = allToolsForBudget.reduce((sum, t) => sum +
-            Math.ceil((t.description.length + JSON.stringify(t.parameters).length) / 4), 0);
+        // Tool definitions are recomputed each iteration so `enable_tools`
+        // (which mutates the shared activeToolTags array) can grow the
+        // LLM-visible tool set mid-run. Bound per-iteration to keep the budget
+        // estimate and boundedOutput set in sync with what is actually sent.
+        let allToolsForBudget = toolExecutor.getToolDefinitions(this.deps.toolTags);
+        let boundedToolNames = new Set(allToolsForBudget.filter((t) => t.boundedOutput).map((t) => t.name));
+        let toolTokenEstimate = allToolsForBudget.reduce((sum, t) => sum + Math.ceil((t.description.length + JSON.stringify(t.parameters).length) / 4), 0);
         contextManager.setToolTokens(toolTokenEstimate);
         while (iteration < config.maxToolIterations && !this.shutdownRequested) {
             iteration++;
             contextManager.noteIteration();
+            // Re-read the mutable tag set in case enable_tools was called.
+            allToolsForBudget = toolExecutor.getToolDefinitions(this.deps.toolTags);
+            boundedToolNames = new Set(allToolsForBudget.filter((t) => t.boundedOutput).map((t) => t.name));
+            toolTokenEstimate = allToolsForBudget.reduce((sum, t) => sum + Math.ceil((t.description.length + JSON.stringify(t.parameters).length) / 4), 0);
+            contextManager.setToolTokens(toolTokenEstimate);
             pluginManager.runOnBeforeThink({
                 iteration,
                 logger,
@@ -202,27 +291,50 @@ export class Agent {
                 },
             });
             if (contextManager.needsCompaction()) {
-                contextManager.compact();
-                logger.debug("Context compacted");
-                slog.logCompaction(`regular compaction, iteration ${iteration}`, iteration);
+                const result = contextManager.compact();
+                if (result) {
+                    logger.debug("Context compacted");
+                    slog.logCompaction({ reason: "interval", iteration, ...result });
+                }
             }
             const currentTokens = contextManager.getEstimatedTokens();
             const budget = contextManager.getBudget();
             const quality = contextManager.getQuality();
             if (quality < QUALITY_TRIGGER_THRESHOLD &&
-                contextManager.getCompactionCount() > 0) {
-                contextManager.compact();
+                contextManager.getCompactionCount() > 0 &&
+                iteration - lastForcedCompactionIteration >= FORCED_COMPACTION_COOLDOWN) {
+                lastForcedCompactionIteration = iteration;
+                const result = contextManager.compact();
                 logger.warn(`Low context quality (${quality}%) — forced compaction`);
-                slog.logCompaction(`quality-triggered compaction (${quality}% < ${QUALITY_TRIGGER_THRESHOLD}%), iteration ${iteration}`, iteration, currentTokens, budget.history);
+                if (result) {
+                    slog.logCompaction({
+                        reason: `quality-triggered (${quality}% < ${QUALITY_TRIGGER_THRESHOLD}%)`,
+                        iteration,
+                        ...result,
+                    });
+                }
             }
             if (currentTokens > budget.history) {
-                contextManager.compact();
+                const result = contextManager.compact();
                 logger.warn(`Context overflow (${currentTokens} > ${budget.history}), forced compaction`);
-                slog.logCompaction(`forced compaction (${currentTokens} > ${budget.history}), iteration ${iteration}`, iteration, currentTokens, budget.history);
+                if (result) {
+                    slog.logCompaction({
+                        reason: `overflow (${currentTokens} > ${budget.history})`,
+                        iteration,
+                        ...result,
+                    });
+                }
             }
             this.refreshSystemPrompt();
             const history = contextManager.getActiveHistory();
             slog.logToolDefs(allToolsForBudget.length, allToolsForBudget.map((t) => t.name), iteration);
+            if (iteration === 1) {
+                const { blocks } = this.buildSystemPrompt();
+                this.logContextStat("start", iteration, slog, blocks);
+            }
+            else {
+                this.logContextStat("iteration", iteration, slog);
+            }
             let textContent = "";
             let reasoningContent = "";
             const toolCalls = [];
@@ -231,6 +343,8 @@ export class Agent {
             const textChunks = [];
             this.emitPhase(iteration, "thinking", onPhase);
             const llmStart = Date.now();
+            const promptBefore = apiPromptTokens;
+            const completionBefore = apiCompletionTokens;
             logger.logLLMRequest(config.model, history.length, input, "agent");
             try {
                 for await (const chunk of llmProvider.chat(history, allToolsForBudget, this.abortController?.signal)) {
@@ -246,7 +360,7 @@ export class Agent {
                     if (chunk.type === "reasoning" && chunk.content) {
                         reasoningContent += chunk.content;
                         if (config.showReasoning) {
-                            const metaOut = pluginManager.runOnMeta({ iteration, logger }, chunk.content);
+                            const metaOut = pluginManager.runOnMeta({ iteration, logger, contextManager }, chunk.content);
                             if (metaOut) {
                                 onMeta?.(pc.dim(metaOut));
                             }
@@ -282,7 +396,7 @@ export class Agent {
                 logger.logLLMResponse(config.model, textContent.length, Date.now() - llmStart, err.message, "agent");
                 logger.error(`LLM call failed: ${err.message}`);
                 slog.logError(err.message);
-                pluginManager.runOnError({ iteration, logger }, err);
+                pluginManager.runOnError({ iteration, logger, contextManager }, err);
                 return {
                     success: false,
                     text: lastText,
@@ -297,6 +411,26 @@ export class Agent {
             // the backend omits `usage` from the response.
             apiCompletionChars += (textContent || reasoningContent).length;
             logger.logLLMResponse(config.model, (textContent || reasoningContent).length, Date.now() - llmStart, undefined, "agent");
+            // Log per-call token usage. llama.cpp streaming often omits `usage`,
+            // so fall back to local estimates (context tokens + chars/4) and
+            // mark the source — the log must distinguish real API numbers from
+            // heuristics.
+            {
+                const usagePrompt = apiPromptTokens - promptBefore;
+                const usageCompletion = apiCompletionTokens - completionBefore;
+                const source = usagePrompt > 0 || usageCompletion > 0 ? "api" : "estimate";
+                const prompt = source === "api" ? usagePrompt : contextManager.getEstimatedTokens();
+                const completion = source === "api"
+                    ? usageCompletion
+                    : Math.ceil((textContent || reasoningContent).length / 4);
+                slog.logLlmUsage(iteration, {
+                    promptTokens: prompt,
+                    completionTokens: completion,
+                    totalTokens: prompt + completion,
+                    source,
+                    durationMs: Date.now() - llmStart,
+                });
+            }
             if (this.shutdownRequested) {
                 break;
             }
@@ -306,11 +440,10 @@ export class Agent {
             // describing the call. `toolComments: false` restores the old behavior
             // of suppressing text next to a tool call.
             const toolComments = this.deps.config.ui?.toolComments ?? true;
-            const showText = textChunks.length > 0 &&
-                (!sawToolCall || (toolComments && !isToolCallJson(textContent)));
+            const showText = textChunks.length > 0 && (!sawToolCall || (toolComments && !isToolCallJson(textContent)));
             if (showText) {
                 for (const chunk of textChunks) {
-                    const textOut = pluginManager.runOnText({ iteration, logger }, chunk);
+                    const textOut = pluginManager.runOnText({ iteration, logger, contextManager }, chunk);
                     onChunk?.(textOut);
                 }
             }
@@ -324,7 +457,7 @@ export class Agent {
             else if (reasoningContent) {
                 llmResponse = { type: "reasoning", content: reasoningContent };
             }
-            pluginManager.runOnAfterThink({ iteration, logger }, llmResponse);
+            pluginManager.runOnAfterThink({ iteration, logger, contextManager }, llmResponse);
             if (this.deps.exitOnComplete && sawToolCall) {
                 const signature = toolCalls
                     .map((tc) => `${tc.name}:${JSON.stringify(tc.arguments)}`)
@@ -371,7 +504,7 @@ export class Agent {
                         toolName: call.name,
                         args: call.arguments,
                     });
-                    pluginManager.runOnToolStart({ iteration, logger }, { id: call.id, name: call.name, arguments: call.arguments });
+                    pluginManager.runOnToolStart({ iteration, logger, contextManager }, { id: call.id, name: call.name, arguments: call.arguments });
                     onTool?.({ type: "start", tool: call.name, args: call.arguments });
                     slog.logToolCall(call, iteration);
                     const tokensBeforeTool = contextManager.getEstimatedTokens();
@@ -382,22 +515,18 @@ export class Agent {
                     if (result.success && call.arguments.path) {
                         const filePath = String(call.arguments.path);
                         if (call.name === "write_file" || call.name === "edit_file") {
-                            hallucinationDetector
-                                .getConsistencyCheck()
-                                .trackCreatedFile(filePath);
+                            hallucinationDetector.getConsistencyCheck().trackCreatedFile(filePath);
                         }
                         else if (call.name === "delete_file") {
-                            hallucinationDetector
-                                .getConsistencyCheck()
-                                .trackDeletedFile(filePath);
+                            hallucinationDetector.getConsistencyCheck().trackDeletedFile(filePath);
                         }
                     }
-                    pluginManager.runOnToolEnd({ iteration, logger }, { id: call.id, name: call.name, arguments: call.arguments }, result, duration);
+                    pluginManager.runOnToolEnd({ iteration, logger, contextManager }, { id: call.id, name: call.name, arguments: call.arguments }, result, duration);
                     if (result.display) {
                         onMeta?.("\n" + result.display + "\n");
                     }
                     else {
-                        const metaOut = pluginManager.runOnMeta({ iteration, logger }, result.output);
+                        const metaOut = pluginManager.runOnMeta({ iteration, logger, contextManager }, result.output);
                         onMeta?.("\n" + pc.dim(metaOut) + "\n");
                     }
                     if (result.diff) {
@@ -405,7 +534,7 @@ export class Agent {
                     }
                     const currentTokens = contextManager.getEstimatedTokens();
                     const budget = contextManager.getBudget();
-                    const truncatedOutput = this.truncateToolOutput(result.output, budget, currentTokens);
+                    const truncatedOutput = this.truncateToolOutput(result.output, budget, currentTokens, boundedToolNames.has(call.name));
                     contextManager.addMessage({
                         role: "tool",
                         content: truncatedOutput,
@@ -428,8 +557,35 @@ export class Agent {
                         slog.logToolResult(call, result, duration, iteration);
                     }
                     if (contextManager.needsCompaction()) {
-                        contextManager.compact();
-                        logger.debug("Context compacted after tool result");
+                        const result = contextManager.compact();
+                        if (result) {
+                            logger.debug("Context compacted after tool result");
+                            slog.logCompaction({
+                                reason: "after_tool",
+                                iteration,
+                                ...result,
+                            });
+                        }
+                    }
+                    // Track per-tool failure counts (NOT just consecutive) so a tool
+                    // that keeps failing while other tools succeed between attempts
+                    // is still learned from (observed: LSP spawn npx ENOENT failed
+                    // 8x in one session, never consecutively, so it never reached
+                    // memory via the 5-consecutive-failures path).
+                    if (!result.success) {
+                        const key = call.name;
+                        const prev = toolFailureCounts.get(key) ?? { count: 0, error: "" };
+                        prev.count++;
+                        prev.error = String(result.output ?? "").slice(0, 200);
+                        toolFailureCounts.set(key, prev);
+                        if (prev.count >= MIN_REPEATED_TOOL_FAILURES && !memoryRuleRecorded.has(key)) {
+                            memoryRuleRecorded.add(key);
+                            const memStore = this.deps.memoryStore;
+                            if (memStore) {
+                                memStore.appendRule("errors", `Tool ${key} failed ${prev.count}x (${prev.error})`, `Repeated ${key} failures suggest a systemic problem (config, environment, or a broken tool), not a one-off`, "Check the error message, verify the tool's dependencies are installed/configured, and consider a different tool");
+                                logger.warn(`Recorded repeated ${key} failures to memory (${prev.count}x)`);
+                            }
+                        }
                     }
                 }
                 if (anyToolFailed) {
@@ -449,13 +605,9 @@ export class Agent {
                         role: "user",
                         content: `<system-summary>${recoveryMsg}\n${taskReminder}</system-summary>`,
                     });
-                    if (sessionManager) {
-                        const activeSession = sessionManager.getActiveMeta();
-                        if (activeSession) {
-                            const memDir = join(baseDir, ".mma", "memory");
-                            const memStore = new MemoryStore(memDir);
-                            memStore.appendRule("errors", `${consecutiveToolFailures} consecutive tool failures`, "Multiple tools failing suggests environment or configuration issue", "Check dependencies, verify file paths, try write_file directly instead of shell commands");
-                        }
+                    const memStore = this.deps.memoryStore;
+                    if (memStore) {
+                        memStore.appendRule("errors", `${consecutiveToolFailures} consecutive tool failures`, "Multiple tools failing suggests environment or configuration issue", "Check dependencies, verify file paths, try write_file directly instead of shell commands");
                     }
                 }
                 contextManager.addMessage({
@@ -483,9 +635,17 @@ export class Agent {
                         onMeta?.(pc.dim(`\n  ⟳ Context compacted (${compCount})\n`));
                     }
                 }
+                // A tool call means the model kept working instead of just
+                // re-answering — the audit-re-answer leniency no longer applies.
+                suppressRepetitionRetry = false;
                 continue;
             }
-            hallucinationDetector.getConfidenceCheck().setPreviousResponse(lastText);
+            hallucinationDetector.getConfidenceCheck().setPreviousResponse(lastModelText);
+            // Update AFTER setPreviousResponse so the comparison uses the
+            // previous iteration's output, not this one (which would otherwise
+            // always overlap with itself).
+            if (textContent)
+                lastModelText = textContent;
             const hallucinationResult = await hallucinationDetector.validate(textContent);
             if (hallucinationResult.status === "block") {
                 logger.warn(`Response blocked: ${hallucinationResult.reason}`);
@@ -517,34 +677,55 @@ export class Agent {
                     lastText = textContent;
                     break;
                 }
-                // NOTE: with exitOnComplete and an EMPTY text we deliberately do NOT
-                // break — the model produced no usable answer yet (same case as the
-                // empty-response guard below). Falling through to the retry path
-                // keeps us from finishing with text: "".
-                if (hallucinationRetries >= MAX_HALLUCINATION_RETRIES) {
-                    logger.warn(`Hallucination retries exhausted (${MAX_HALLUCINATION_RETRIES}), returning error`);
-                    return {
-                        success: false,
-                        text: lastText,
-                        error: t("error.response_blocked", {
-                            reason: t("hall.max_retries_exhausted"),
-                        }),
-                        iterationCount: iteration,
-                    };
+                if (suppressRepetitionRetry && hallucinationResult.kind === "repetition") {
+                    // The audit gate rejected the previous final answer and
+                    // re-prompted the model. Its re-answer restating the completed
+                    // task is naturally "repetitive" — that is expected, not
+                    // degeneration. Downgrade to a warning and let the response
+                    // flow through to the final audit gate again (which is itself
+                    // bounded by MAX_AUDIT_RETRIES).
+                    suppressRepetitionRetry = false;
+                    logger.warn(`Audit-triggered re-answer repetition — not counted as hallucination retry`);
+                    const warnLine = `${t("hall.uncertainty_prefix").trim()} ${hallucinationResult.reason ?? ""}`;
+                    if (onMeta) {
+                        onMeta(`\n${pc.yellow(warnLine)}\n`);
+                    }
+                    else if (onChunk) {
+                        onChunk(`\n${warnLine}\n`);
+                    }
+                    // fall through to the acceptance path below (assistant message,
+                    // lastText, final audit gate).
                 }
-                hallucinationRetries++;
-                logger.warn(`Hallucination retry (${hallucinationRetries}/${MAX_HALLUCINATION_RETRIES}): ${hallucinationResult.reason}`);
-                if (textContent) {
+                else {
+                    // NOTE: with exitOnComplete and an EMPTY text we deliberately
+                    // do NOT break — the model produced no usable answer yet (same
+                    // case as the empty-response guard below). Falling through to
+                    // the retry path keeps us from finishing with text: "".
+                    if (hallucinationRetries >= MAX_HALLUCINATION_RETRIES) {
+                        logger.warn(`Hallucination retries exhausted (${MAX_HALLUCINATION_RETRIES}), returning error`);
+                        return {
+                            success: false,
+                            text: lastText,
+                            error: t("error.response_blocked", {
+                                reason: t("hall.max_retries_exhausted"),
+                            }),
+                            iterationCount: iteration,
+                        };
+                    }
+                    hallucinationRetries++;
+                    logger.warn(`Hallucination retry (${hallucinationRetries}/${MAX_HALLUCINATION_RETRIES}): ${hallucinationResult.reason}`);
+                    if (textContent) {
+                        contextManager.addMessage({
+                            role: "assistant",
+                            content: textContent,
+                        });
+                    }
                     contextManager.addMessage({
-                        role: "assistant",
-                        content: textContent,
+                        role: "user",
+                        content: `<system-summary>[Retry context: ${hallucinationResult.reason}. Original task: "${input}". You must either call a needed tool or provide a substantive response. Empty replies are not allowed.]</system-summary>`,
                     });
+                    continue;
                 }
-                contextManager.addMessage({
-                    role: "user",
-                    content: `<system-summary>[Retry context: ${hallucinationResult.reason}. Original task: "${input}". You must either call a needed tool or provide a substantive response. Empty replies are not allowed.]</system-summary>`,
-                });
-                continue;
             }
             if (textContent) {
                 contextManager.addMessage({ role: "assistant", content: textContent });
@@ -596,11 +777,16 @@ export class Agent {
                         });
                         slog.logAudit(audit.summary, iteration);
                         auditRetries++;
-                        if (auditRetries >= MAX_AUDIT_RETRIES ||
-                            iteration >= config.maxToolIterations - 1) {
-                            logger.warn(`Final audit still incomplete after ${auditRetries} retries — finishing anyway`);
+                        lastAuditSummary = audit.summary;
+                        if (auditRetries >= MAX_AUDIT_RETRIES || iteration >= config.maxToolIterations - 1) {
+                            logger.warn(`Final audit still incomplete after ${auditRetries} retries — reporting failure`);
+                            auditFailed = true;
                             break;
                         }
+                        // The next non-tool response is a forced re-answer of an
+                        // already-completed task — allow one repetition without
+                        // burning the hallucination budget (see retry branch).
+                        suppressRepetitionRetry = true;
                         continue;
                     }
                 }
@@ -626,9 +812,13 @@ export class Agent {
             };
         }
         return {
-            success: emptyResponseExhausted ? false : true,
+            success: emptyResponseExhausted || auditFailed ? false : true,
             text: lastText,
-            error: emptyResponseExhausted ? t("error.empty_response") : undefined,
+            error: emptyResponseExhausted
+                ? t("error.empty_response")
+                : auditFailed
+                    ? t("error.audit_failed", { summary: lastAuditSummary })
+                    : undefined,
             iterationCount: iteration,
             contextUsed: tokensUsed,
             contextLimit: budget.history,
@@ -690,6 +880,7 @@ export class Agent {
         pluginManager.runOnSessionEnd({
             logger,
             sessionManager: sessionManager?.getActiveMeta(),
+            contextManager,
         });
     }
 }