@ikarmic/forge-core 5.2.0 → 5.4.0

package/dist/agent/agent.js

@@ -2,13 +2,19 @@ import { existsSync } from 'node:fs';
 import { release } from 'node:os';
 import path from 'node:path';
 import { streamText } from 'ai';
+import { formatFile, formatMessage } from '../format/auto-format.js';
+import { BackgroundProcesses } from '../tools/background-process.js';
+import { networkDenial } from '../tools/network-policy.js';
+import { runnerShell } from '../tools/shell.js';
+import { cancelWakeupTool, scheduleWakeupTool } from '../wakeup/wakeup-tools.js';
 import { lintFile, lintMessage } from '../lint/auto-lint.js';
 import { buildMemoryBlock } from '../memory/memory-store.js';
 import { filesTouchedBy } from '../tools/write-tools.js';
 import { buildExtraInstructionsBlock } from '../steering/extra-instructions.js';
 import { buildProjectInstructionsBlock } from '../steering/project-instructions.js';
 import { buildRepoMap, repoMapBlock } from '../repomap/repo-map.js';
-import { buildLlmSummarizer, compactMessages, effectiveLimitTokens, getModelWindowTokens, shouldCompactForBudget } from '../context/compaction.js';
+import { adaptHistoryForModel, normalizeForModel } from './history-adapt.js';
+import { buildLlmSummarizer, compactMessages, effectiveLimitTokens, estimateMessageTokens, getModelWindowTokens, shouldCompactForBudget } from '../context/compaction.js';
 import { createStepMasker } from '../context/mask.js';
 import { lookupPricing, computeCostUsd } from '../pricing.js';
 import { BrowserSession } from '../browser/session.js';
@@ -19,6 +25,7 @@ import { createCodebaseSearchTool } from '../tools/codebase-search.js';
 import { createGitHubTools, githubFromEnv } from '../github/github-tools.js';
 import { createWebSearchTool, webSearchFromEnv } from '../tools/web-search.js';
 import { embedderFromEnv } from '../semantic/embedder.js';
+import { capToolResult } from '../tools/result-cap.js';
 import { DEFAULT_VERIFY_RETRIES, failureMessage, runVerification } from './verify.js';
 import { LoopGuard, resultKeyOf } from './loop-guard.js';
 import { isListedCommand } from '../tools/command-allow.js';
@@ -27,17 +34,29 @@ import { createLanguageModel } from '../providers.js';
 import { BUILTIN_TOOLS } from '../tools/index.js';
 import { ToolResultCache, cachedExecute } from '../tools/result-cache.js';
 import { ThinkSplitter, stripThinkTags } from './think-tags.js';
+import { repairToolCall } from './tool-repair.js';
+import { maxOutputTokensFor } from '../catalog/models-dev.js';
 import { redact } from '../tools/redact.js';
-import { composeSkillsPrompt, selectSkills } from '../skills/activator.js';
+import { buildSkillIndex, composeSkillsPrompt, selectSkills } from '../skills/activator.js';
+import { createSkillTool } from '../skills/skill-tool.js';
 import { MAX_TOOL_INJECTIONS, selectAtStart, selectOnToolTouch, toWorkspaceRelative, wrapSteering } from '../steering/select.js';
-import { applyCacheHints } from './cache-hints.js';
+import { applyCacheHints, cacheProviderOptions } from './cache-hints.js';
 import { raceAbort } from './race-abort.js';
-import { attachmentParts, formatBytes, mediaPartTokens } from '../attachments.js';
+import { DEFAULT_PROVIDER_RETRIES, DEFAULT_RETRY_BASE_MS, defaultNetworkProbe, errorSummary, isContextOverflowError, isDisconnected, retryDecision, waitForNetwork, waitOrAbort, } from './retry.js';
+import { attachmentParts, formatBytes } from '../attachments.js';
 import { renderAnswersBlock } from '../journey/answers-block.js';
-import { CONTINUE_PROMPT, DEFAULT_PLAN_MODE_SUFFIX, DEFAULT_SPEC_MODE_SUFFIX, DEFAULT_SYSTEM_PROMPT, environmentBlock } from './prompts.js';
+import { CONTINUE_PROMPT, DEFAULT_PLAN_MODE_SUFFIX, DEFAULT_SPEC_MODE_SUFFIX, DEFAULT_SYSTEM_PROMPT, LAST_STEP_PROMPT, environmentBlock, modelGuidanceBlock, todoNudgePrompt } from './prompts.js';
 import { detectStackFacts, stackBlock } from './stack-facts.js';
 /** Read-only tool names whose output flows through the redactor. */
 const DEFAULT_MAX_CONTINUATIONS = 3;
+/** Nudges per run when a turn ends with open todos; never two without a tool call between them. */
+const MAX_TODO_NUDGES = 3;
+/** Times an empty or reasoning-only reply is asked for again before it is accepted. */
+const MAX_EMPTY_REPLAYS = 2;
+/** Consecutive tool calls with invalid arguments before the run stops (Kilo: REPEATED_TOOL_FAILURE_LIMIT). */
+const MAX_INVALID_CALLS = 3;
+/** Most recent content kept word for word by compaction, at the top end (RB-56). */
+const KEEP_RECENT_TOKENS = 20_000;
 export const DEFAULT_MAX_DURATION_MS = 10 * 60 * 1000;
 const REDACTABLE_TOOLS = new Set(['read_file', 'search_files', 'list_files']);
 /** Tools whose successful `path` argument can trigger mid-run fileMatch steering. */
@@ -74,6 +93,12 @@ export class Agent {
         const allTools = (config.disableBuiltins
             ? [...(config.extraTools ?? [])]
             : [...BUILTIN_TOOLS, ...(config.extraTools ?? [])]);
+        // Wakeups need a chat that can deliver them, so the tools exist only when a surface supplied a scheduler.
+        // The `skill` tool goes with the skills index in the prompt: both exist only when a registry is supplied and not disabled.
+        if (config.skills && !config.skills.disabled)
+            allTools.push(createSkillTool(config.skills.registry));
+        if (config.wakeups)
+            allTools.push(scheduleWakeupTool, cancelWakeupTool);
         if (config.browser) {
             this.browser = new BrowserSession(config.browser === true ? {} : config.browser);
             allTools.push(...createBrowserTools(this.browser));
@@ -89,6 +114,8 @@ export class Agent {
                 ...(config.semanticSearch.extensions ? { extensions: config.semanticSearch.extensions } : {}),
                 ...(config.semanticSearch.minScore !== undefined ? { minScore: config.semanticSearch.minScore } : {}),
                 ...(config.semanticSearch.defaultLimit ? { defaultLimit: config.semanticSearch.defaultLimit } : {}),
+                ...(config.semanticSearch.consent ? { consent: config.semanticSearch.consent } : {}),
+                ...(config.semanticSearch.onStatus ? { onStatus: config.semanticSearch.onStatus } : {}),
             }));
         }
         const memoryFiltered = config.disableMemory
@@ -116,7 +143,7 @@ export class Agent {
         const cfg = this.checkpoints?.captureBeforeTools;
         if (!cfg) {
             // Default: file-mutating tools + run_command (which can mutate via shell).
-            return new Set(['write_file', 'edit_file', 'edit_notebook', 'apply_patch', 'run_command']);
+            return new Set(['write_file', 'edit_file', 'edit_notebook', 'apply_patch', 'run_command', 'bg_start']);
         }
         return new Set(cfg);
     }
@@ -190,9 +217,15 @@ export class Agent {
         /** Docs injected mid-run (not skipped ones), so compaction can tell which it removed. */
         const steeringInMessages = new Set();
         let steeringInjections = 0;
+        // The system message is rebuilt on every turn from what is true now (RB-57): files, steering, the mode's prompt
+        // and the date can change between turns. Built in a stable order, it is byte-identical when nothing changed.
+        const systemSteering = options.history
+            ? selectAtStart(steeringDocs, { task: options.task, cwd, includeAlways: true }, this.config.steering?.maxBytes).system
+            : startSteering.system;
+        const system = { role: 'system', content: await buildSystemContent(this.config, options.task, this.skills, systemSteering) };
         const messages = options.history
-            ? [...options.history, { role: 'user', content: userContent }]
-            : await buildInitialMessages(this.config, options.task, this.skills, startSteering.system, userContent);
+            ? [system, ...adaptHistoryForModel(options.history, this.config.model).filter((m, i) => !(i === 0 && m.role === 'system')), { role: 'user', content: userContent }]
+            : [system, { role: 'user', content: userContent }];
         if (options.attachments && options.attachments.length > 0) {
             // Attached files ride in this turn's user message as native parts (see attachments.ts).
             messages[messages.length - 1] = {
@@ -200,6 +233,18 @@ export class Agent {
                 content: [{ type: 'text', text: userContent }, ...attachmentParts(options.attachments)],
             };
         }
+        // This turn's messages on their own (RB-58): compaction replaces `messages`, never these, so a surface can show
+        // the whole conversation. Everything the run adds goes through append().
+        const turnMessages = [messages[messages.length - 1]];
+        const append = (m) => {
+            messages.push(m);
+            turnMessages.push(m);
+        };
+        const unappend = () => {
+            const last = messages.pop();
+            if (last !== undefined && turnMessages[turnMessages.length - 1] === last)
+                turnMessages.pop();
+        };
         // Plan mode: hard-cap iterations to 1 and add a system prompt suffix
         // telling the model to emit a plan as text and stop. Spec mode: allow
         // up to `specMaxIterations` turns (default 15) so the model can
@@ -219,6 +264,7 @@ export class Agent {
             ? createStepMasker({
                 keepRecentTurns: (typeof maskConfig === 'object' ? maskConfig.keepRecentTurns : undefined) ?? 6,
                 minChars: (typeof maskConfig === 'object' ? maskConfig.minChars : undefined) ?? 600,
+                ...(typeof maskConfig === 'object' && maskConfig.protectTokens !== undefined ? { protectTokens: maskConfig.protectTokens } : {}),
                 softBudgetTokens: 0.5 * effectiveLimitTokens(this.config.model, this.config.compactionThreshold ?? 0.7, this.config.contextBudgetTokens),
             })
             : undefined;
@@ -234,6 +280,8 @@ export class Agent {
         let reportedStreamError;
         const modelFactory = this.config.modelFactory ?? createLanguageModel;
         let currentModelConfig = this.config.model;
+        /** The prompt size at which to compact for a given model: its window times the threshold, or the budget. */
+        const limitOf = (m) => effectiveLimitTokens(m, this.config.compactionThreshold ?? 0.7, this.config.contextBudgetTokens);
         let model = modelFactory(currentModelConfig);
         let stepPricing = this.pricing;
         let lastToolNames = [];
@@ -259,6 +307,26 @@ export class Agent {
         let partialStepText = '';
         let continuations = 0;
         const maxContinuations = this.config.maxContinuations ?? DEFAULT_MAX_CONTINUATIONS;
+        // Open-todo nudges: the one sent last (so a run that ends before answering it drops it) and whether
+        // the step just answered was a nudge (a second text-only reply in a row is the model's answer).
+        // Only a list this run wrote counts: the chat carries the last turn's list over, and an unrelated
+        // question answered while it is open must not be pushed back onto the old task.
+        let todoNudges = 0;
+        let todoNudgeMessage;
+        let answeringNudge = false;
+        let todosWrittenThisRun = false;
+        // Provider failures and empty replies retried for the step now running; both reset when a step succeeds.
+        const maxProviderRetries = this.config.providerRetry?.maxRetries ?? DEFAULT_PROVIDER_RETRIES;
+        const retryBaseMs = this.config.providerRetry?.baseDelayMs ?? DEFAULT_RETRY_BASE_MS;
+        let providerFailures = 0;
+        let emptyReplays = 0;
+        // Time spent waiting for the network in this run, across every offline spell.
+        const offlinePollMs = this.config.providerRetry?.offlinePollMs ?? 3000;
+        const maxOfflineMs = this.config.providerRetry?.maxOfflineMs ?? 15 * 60_000;
+        let offlineWaitedMs = 0;
+        let offlineWaits = 0;
+        // Consecutive tool calls whose arguments failed the schema, across steps; any valid call resets it.
+        let invalidStreak = { tool: '', count: 0 };
         const ctx = {
             cwd: this.config.cwd ?? process.cwd(),
             auto: this.config.auto ?? false,
@@ -269,20 +337,69 @@ export class Agent {
             ...(this.config.permissionRules ? { permissionRules: this.config.permissionRules } : {}),
             ...(this.config.toolSandbox ? { toolSandbox: this.config.toolSandbox } : {}),
             shownFolderInstructions: new Set(),
+            processes: new BackgroundProcesses(),
+            ...(this.config.shell ? { shell: this.config.shell } : {}),
+            // Earlier grants of this chat (G16), then whatever repo_clone and a yes to a question add during the run.
+            readRoots: [...(this.config.readRoots ?? [])],
+            ...(this.config.askReadOutside ? { askReadOutside: this.config.askReadOutside } : {}),
+            ...(this.config.suggestPlan ? { suggestPlan: true } : {}),
+            ...(this.config.planDeclined ? { planDeclined: true } : {}),
+            ...(this.config.wakeups ? { wakeups: this.config.wakeups } : {}),
             ...(this.config.maxToolOutputChars ? { maxOutputChars: this.config.maxToolOutputChars } : {}),
+            ...(typeof this.config.verify?.lsp === 'object' ? { lspConfig: this.config.verify.lsp } : {}),
             ...(this.config.askUser ? { askUser: this.config.askUser } : {}),
             ...(this.config.askBudget ? { askBudget: this.config.askBudget } : {}),
             todos: {
                 get: () => this.todoList,
                 set: (todos) => {
                     this.todoList = todos;
+                    todosWrittenThisRun = true;
                     emit({ type: 'todo_updated', todos });
                 },
             },
             ...(this.config.commandRunner ? { commandRunner: this.config.commandRunner } : {}),
+            ...(this.config.commandSandbox ? { commandSandbox: this.config.commandSandbox } : {}),
             ...(abortSignal ? { abortSignal } : {}),
             ...(this.config.memoryMaxBodyChars !== undefined ? { memoryMaxBodyChars: this.config.memoryMaxBodyChars } : {}),
         };
+        // Summarize older turns in place; returns how many messages were dropped (0: nothing could be compacted).
+        const compactNow = async (tokens) => {
+            if (this.hooks) {
+                await this.hooks.dispatch({ type: 'PreCompact', messagesCount: messages.length, tokens, cwd });
+            }
+            const summarizer = this.config.compactionSummarizer ?? this.buildDefaultSummarizer();
+            const limit = limitOf(currentModelConfig);
+            const result = await compactMessages(messages, summarizer, {
+                keepRecent: this.config.compactionKeepRecent,
+                keepRecentTokens: Math.min(KEEP_RECENT_TOKENS, Math.floor(limit / 4)),
+            });
+            if (result.droppedCount === 0)
+                return 0;
+            // The last reported size describes the prompt before compaction; until the next call reports, the estimate rules.
+            lastTurnInputTokens = 0;
+            messages.length = 0;
+            for (const m of result.messages)
+                messages.push(m);
+            masker?.reset(); // the history was replaced, so the frozen boundary no longer applies
+            // A mid-run steering doc summarized away may be injected again on the next touch.
+            for (const name of [...steeringInMessages]) {
+                const marker = `<steering name="${name}">`;
+                if (messages.some((m) => typeof m.content === 'string' && m.content.includes(marker)))
+                    continue;
+                steeringInMessages.delete(name);
+                steeringInjected.delete(name);
+                steeringInjections--;
+            }
+            emit({
+                type: 'compaction',
+                droppedCount: result.droppedCount,
+                savedTokens: result.savedTokens,
+                summary: result.summary,
+            });
+            return result.droppedCount;
+        };
+        // The provider refused the prompt as too long: compact once and ask again (Kilo does the same).
+        let overflowCompactions = 0;
         // Emit initial cache stats so the UI knows the cache is wired up.
         emit({ type: 'cache_stats', ...this.cache.getStats() });
         try {
@@ -327,6 +444,7 @@ export class Agent {
                 // Track per-turn token deltas so we can compute per-turn cost.
                 const turnStart = { input: inputTokens, output: outputTokens, cacheRead: cacheReadTokens, cacheWrite: cacheWriteTokens };
                 let reasoningText = '';
+                let stepFailure;
                 partialStepText = '';
                 // Inline <think> blocks (MiniMax over OpenAI-compatible, some open models) become reasoning events.
                 const thinkSplitter = new ThinkSplitter();
@@ -348,27 +466,54 @@ export class Agent {
                     }
                     wasInThink = thinkSplitter.reasoning;
                 };
+                if (!planMode && !specMode && this.config.enableCompaction) {
+                    const before = Math.max(lastTurnInputTokens, estimateMessageTokens(messages));
+                    if (before >= limitOf(currentModelConfig))
+                        await compactNow(before);
+                }
                 let promptMessages = messages;
                 if (masker) {
-                    const view = masker.apply(messages, Math.max(lastTurnInputTokens, estimateNextPromptTokens(messages)));
-                    promptMessages = view.messages;
+                    const view = masker.apply(messages, Math.max(lastTurnInputTokens, estimateMessageTokens(messages)));
+                    // Stubs are stored in the prompt history (RB-60), so the next turn sends the same prefix and the cache hits.
+                    // The full results stay in turnMessages, which the transcript keeps (RB-58).
+                    for (let i = 0; i < messages.length; i++)
+                        if (view.messages[i] !== messages[i])
+                            messages[i] = view.messages[i];
+                    promptMessages = messages;
                     if (view.stepped)
                         emit({ type: 'context_masked', maskedCount: view.maskedCount, savedTokens: Math.ceil(view.savedChars / 4) });
                 }
+                // The last allowed step: no tools, and a note asking for a summary instead of stopping mid-task.
+                const lastStep = !planMode && !specMode && effectiveMaxIter > 1 && iterations >= effectiveMaxIter;
+                if (lastStep)
+                    promptMessages = [...promptMessages, { role: 'user', content: LAST_STEP_PROMPT }];
                 const result = streamText({
                     model,
-                    messages: cachePrompts ? applyCacheHints(promptMessages, currentModelConfig) : promptMessages,
+                    // Per-provider clean-up on every call (RB-61), then cache breakpoints on the cleaned messages.
+                    messages: cachePrompts
+                        ? applyCacheHints(normalizeForModel(promptMessages, currentModelConfig), currentModelConfig)
+                        : normalizeForModel(promptMessages, currentModelConfig),
+                    ...(cachePrompts && cacheProviderOptions(currentModelConfig, this.config.sessionId)
+                        ? { providerOptions: cacheProviderOptions(currentModelConfig, this.config.sessionId) }
+                        : {}),
                     // v7 rejects a system-role message inside `messages` by default
                     // ("Invalid prompt: System messages are not allowed in the prompt
                     // or messages fields. Use the instructions option instead.").
-                    // Forge's system prompt lives as messages[0] (buildInitialMessages)
+                    // Forge's system prompt lives as messages[0] (buildSystemContent)
                     //: this is the SDK's own documented escape hatch to keep that
                     // architecture rather than restructuring session persistence and
                     // compaction (both of which also treat messages[0] as the system
                     // message) around a separate `system` option.
                     allowSystemInMessages: true,
                     tools: toAiSdkTools(this.tools),
+                    repairToolCall,
+                    // Ask for the model's own reply length (G8): some hosts default to a few thousand tokens, which cuts a long
+                    // write_file call in half. A half-written tool call cannot be continued, unlike text.
+                    ...(maxOutputTokensFor(currentModelConfig) ? { maxOutputTokens: maxOutputTokensFor(currentModelConfig) } : {}),
+                    ...(lastStep ? { toolChoice: 'none' } : {}),
                     abortSignal,
+                    // Retries are decided below (retryDecision), for failures before and during the stream alike.
+                    maxRetries: 0,
                     ...(this.config.model.reasoningEffort ? { reasoning: this.config.model.reasoningEffort } : {}),
                     ...(this.config.model.temperature !== undefined ? { temperature: this.config.model.temperature } : {}),
                     onChunk: ({ chunk }) => {
@@ -388,8 +533,9 @@ export class Agent {
                         // Pressing Stop aborts the request; that is not a failure to report.
                         if (abortSignal?.aborted)
                             return;
+                        // Reported only if it is not retried (below); the SDK then throws a generic "No output generated".
+                        stepFailure = error;
                         reportedStreamError = errorMessageOf(error);
-                        emit({ type: 'error', error: reportedStreamError });
                     },
                     onFinish: ({ text: rawText, usage }) => {
                         emitSegments(thinkSplitter.flush());
@@ -439,14 +585,90 @@ export class Agent {
                         }
                     },
                 });
-                await result.consumeStream();
-                finalText = continuedText + stripThinkTags(await result.text);
+                let stepText;
+                let toolCalls;
+                let response;
+                try {
+                    await result.consumeStream();
+                    stepText = stripThinkTags(await result.text);
+                    toolCalls = await result.toolCalls;
+                    response = await result.response;
+                    if (stepFailure !== undefined)
+                        throw stepFailure;
+                }
+                catch (err) {
+                    if (abortSignal?.aborted)
+                        throw err;
+                    const failure = stepFailure ?? err;
+                    stepFailure = undefined;
+                    if (isContextOverflowError(failure) && this.config.enableCompaction && !planMode && !specMode && overflowCompactions < 2) {
+                        overflowCompactions++;
+                        if ((await compactNow(Math.max(lastTurnInputTokens, estimateMessageTokens(messages)))) > 0) {
+                            partialStepText = '';
+                            iterations--;
+                            continue;
+                        }
+                    }
+                    // No network at all: wait for it to come back instead of spending retries (Kilo's offline guard).
+                    // Only when a probe confirms it: a mistyped provider host fails DNS too while the network is fine.
+                    const probe = this.config.providerRetry?.networkProbe ?? defaultNetworkProbe;
+                    if (isDisconnected(failure) && offlineWaitedMs < maxOfflineMs && !(await probe().catch(() => false))) {
+                        offlineWaits++;
+                        emit({ type: 'retry', kind: 'offline', attempt: offlineWaits, maxRetries: 0, delayMs: offlinePollMs, reason: errorSummary(failure) });
+                        const waited = await waitForNetwork(probe, {
+                            pollMs: offlinePollMs,
+                            budgetMs: maxOfflineMs - offlineWaitedMs,
+                            ...(abortSignal ? { abortSignal } : {}),
+                        });
+                        offlineWaitedMs += waited.waitedMs;
+                        if (waited.outcome === 'aborted') {
+                            reason = 'aborted';
+                            break;
+                        }
+                        if (waited.outcome === 'online') {
+                            partialStepText = '';
+                            iterations--;
+                            continue;
+                        }
+                        throw failure;
+                    }
+                    const decision = retryDecision(failure, providerFailures + 1, retryBaseMs);
+                    if (!decision.retry || providerFailures >= maxProviderRetries)
+                        throw failure;
+                    providerFailures++;
+                    // The step is thrown away whole: nothing it streamed is kept, and it does not count as a step.
+                    partialStepText = '';
+                    emit({ type: 'retry', kind: 'provider_error', attempt: providerFailures, maxRetries: maxProviderRetries, delayMs: decision.delayMs, reason: decision.message });
+                    iterations--;
+                    if ((await waitOrAbort(decision.delayMs, abortSignal)) === 'aborted') {
+                        reason = 'aborted';
+                        break;
+                    }
+                    continue;
+                }
+                // A reply with neither text nor a tool call (empty, or reasoning only) is an unfinished answer, not the end.
+                if ((!toolCalls || toolCalls.length === 0) &&
+                    !stepText.trim() &&
+                    !continuedText &&
+                    (await result.finishReason) !== 'length' &&
+                    emptyReplays < MAX_EMPTY_REPLAYS) {
+                    emptyReplays++;
+                    const delayMs = retryBaseMs * emptyReplays;
+                    emit({ type: 'retry', kind: 'empty_reply', attempt: emptyReplays, maxRetries: MAX_EMPTY_REPLAYS, delayMs, reason: 'The model sent an empty reply.' });
+                    iterations--;
+                    if ((await waitOrAbort(delayMs, abortSignal)) === 'aborted') {
+                        reason = 'aborted';
+                        break;
+                    }
+                    continue;
+                }
+                providerFailures = 0;
+                emptyReplays = 0;
+                finalText = continuedText + stepText;
                 continuedText = '';
-                const toolCalls = await result.toolCalls;
                 lastToolNames = (toolCalls ?? []).map((c) => c.toolName);
-                const response = await result.response;
                 for (const m of response.messages) {
-                    messages.push(m);
+                    append(m);
                 }
                 // Infinite output: a reply cut off by the output-token limit (and not
                 // calling tools) is continued with a follow-up user message rather
@@ -458,7 +680,7 @@ export class Agent {
                     continuations++;
                     continuedText = finalText;
                     emit({ type: 'continuation', count: continuations });
-                    messages.push({ role: 'user', content: CONTINUE_PROMPT });
+                    append({ role: 'user', content: CONTINUE_PROMPT });
                     continue;
                 }
                 if (!toolCalls || toolCalls.length === 0) {
@@ -479,6 +701,22 @@ export class Agent {
                         reason = 'spec';
                         break;
                     }
+                    // A reply that ends the turn while the model's own todo list has open items ("Now I'll implement X…")
+                    // is usually a stall, not an answer. Nudge once, if the model can still update the list and has a step left.
+                    const openTodos = this.todoList.filter((t) => t.status !== 'completed');
+                    if (openTodos.length > 0 &&
+                        todosWrittenThisRun &&
+                        !answeringNudge &&
+                        todoNudges < MAX_TODO_NUDGES &&
+                        iterations < effectiveMaxIter &&
+                        this.tools.some((t) => t.name === 'todo_write')) {
+                        todoNudges++;
+                        answeringNudge = true;
+                        todoNudgeMessage = { role: 'user', content: todoNudgePrompt(openTodos) };
+                        append(todoNudgeMessage);
+                        emit({ type: 'todo_nudge', open: openTodos.length });
+                        continue;
+                    }
                     if (this.config.verify && (this.config.verify.commands.length > 0 || this.config.verify.lsp) && editedSinceVerify) {
                         if (verifyApproved === undefined) {
                             // Like a tool approval, the question must not outlive Stop: race it against the abort signal.
@@ -518,13 +756,14 @@ export class Agent {
                         verification = { passed: outcome.passed, attempts: verifyAttempts };
                         if (!outcome.passed && verifyFixes < (this.config.verify.maxRetries ?? DEFAULT_VERIFY_RETRIES)) {
                             verifyFixes++;
-                            messages.push({ role: 'user', content: failureMessage(outcome.failures) });
+                            append({ role: 'user', content: failureMessage(outcome.failures) });
                             continue;
                         }
                     }
                     reason = 'completed';
                     break;
                 }
+                answeringNudge = false;
                 // Resolve which tools the model called (only those without `execute`
                 // reach this code path; tools with `execute` are handled by the SDK).
                 const toolResultMessages = [];
@@ -540,12 +779,14 @@ export class Agent {
                     }
                     const argsParsed = def.parameters.safeParse(call.input);
                     if (!argsParsed.success) {
+                        invalidStreak = { tool: call.toolName, count: invalidStreak.count + 1 };
                         const message = `Invalid arguments for ${call.toolName}: ${argsParsed.error.message}`;
                         trackLoop(call.toolName, call.input, message);
                         currentToolResults.push(toolResultError(call.toolCallId, call.toolName, message));
                         emit({ type: 'tool_result', name: call.toolName, id: call.toolCallId, result: message, isError: true });
                         continue;
                     }
+                    invalidStreak = { tool: '', count: 0 };
                     const approval = await this.requestApproval(def, call.toolCallId, argsParsed.data, abortSignal, ctx);
                     this.audit?.record({ event: 'tool_call', tool: call.toolName, args: approval.args ?? argsParsed.data, approved: approval.approved, auto: this.config.auto === true }, auditCtx);
                     if (!approval.approved) {
@@ -569,7 +810,7 @@ export class Agent {
                         }
                         toolArgs = edited.data;
                     }
-                    emit({ type: 'tool_call', name: call.toolName, id: call.toolCallId, args: toolArgs });
+                    emit({ type: 'tool_call', name: call.toolName, id: call.toolCallId, args: toolArgs, ...(approval.source ? { approval: approval.source } : {}) });
                     if (this.hooks) {
                         await this.hooks.dispatch({
                             type: 'PreToolUse',
@@ -599,12 +840,17 @@ export class Agent {
                     }
                     const toolStartedAt = Date.now();
                     try {
-                        const rawResult = await def.execute(toolArgs, {
+                        // With the sandbox's network off, Forge's own network tools are held to its allowed hosts, from one place (F13).
+                        const denied = networkDenial(def.name, toolArgs, this.config.commandSandbox);
+                        if (denied)
+                            throw new Error(`[sandbox] ${denied}`);
+                        // One size limit for every tool, not only run_command (G6).
+                        const rawResult = capToolResult(await def.execute(toolArgs, {
                             ...ctx,
                             policy: this.config.toolSandbox?.policies?.[def.name],
                             onProgress: (msg) => emit({ type: 'text_delta', text: `\n[${def.name}] ${msg}\n` }),
                             onChildProgress: (event) => emit({ type: 'tool_result', name: def.name, id: call.toolCallId, result: `[child] ${event.event.type}`, isError: false }),
-                        });
+                        }), this.config.maxToolOutputChars);
                         // Apply redaction to read-style tool output. The model gets the
                         // scrubbed version; the user (via the on-event stream) sees the
                         // count so they know something was hidden.
@@ -625,6 +871,15 @@ export class Agent {
                         if (FILE_WRITE_TOOLS.has(call.toolName))
                             for (const p of touchedFiles)
                                 editedFiles.add(p);
+                        if (this.config.autoFormat && FILE_WRITE_TOOLS.has(call.toolName)) {
+                            for (const editedPath of touchedFiles) {
+                                const note = formatMessage(editedPath, await formatFile(editedPath, this.config.autoFormat, { ...ctx, policy: undefined }));
+                                if (note)
+                                    finalResult = typeof finalResult === 'string' ? `${finalResult}
+
+${note}` : { result: finalResult, autoFormat: note };
+                            }
+                        }
                         if (this.config.autoLint && FILE_WRITE_TOOLS.has(call.toolName)) {
                             for (const editedPath of touchedFiles) {
                                 const report = await lintFile(editedPath, this.config.autoLint, { ...ctx, policy: undefined }).catch(() => null);
@@ -694,12 +949,18 @@ export class Agent {
                     toolResultMessages.push({ role: 'tool', content: currentToolResults });
                 }
                 for (const m of toolResultMessages)
-                    messages.push(m);
+                    append(m);
                 if (loopTripped) {
                     emit({ type: 'loop_detected', tool: loopTripped.tool, count: loopTripped.count });
                     reason = 'loop_detected';
                     break;
                 }
+                if (invalidStreak.count >= MAX_INVALID_CALLS) {
+                    errorMessage = `Stopped: the model sent invalid arguments for ${invalidStreak.tool} ${invalidStreak.count} times in a row.`;
+                    emit({ type: 'error', error: errorMessage });
+                    reason = 'error';
+                    break;
+                }
                 // Mid-run fileMatch steering: one extra user message per round, each doc once per run.
                 if (steeringDocs.length > 0 && touchedPaths.length > 0) {
                     const injected = [];
@@ -722,7 +983,7 @@ export class Agent {
                         }
                     }
                     if (injected.length > 0) {
-                        messages.push({ role: 'user', content: injected.map(wrapSteering).join('\n\n') });
+                        append({ role: 'user', content: injected.map(wrapSteering).join('\n\n') });
                     }
                 }
                 // Emit updated cache stats after the tool round so the UI sees hits.
@@ -737,41 +998,9 @@ export class Agent {
                     // Two independent estimates of "how big is the next prompt": 
                     // take the larger rather than summing them (they're not additive
                     // components of the same total, they're two guesses at it).
-                    const totalForNextTurn = Math.max(lastTurnInputTokens, estimateNextPromptTokens(messages));
-                    if (shouldCompactForBudget(totalForNextTurn, this.config.model, threshold, this.config.contextBudgetTokens)) {
-                        if (this.hooks) {
-                            await this.hooks.dispatch({
-                                type: 'PreCompact',
-                                messagesCount: messages.length,
-                                tokens: totalForNextTurn,
-                                cwd,
-                            });
-                        }
-                        const summarizer = this.config.compactionSummarizer ?? this.buildDefaultSummarizer();
-                        const result = await compactMessages(messages, summarizer, {
-                            keepRecent: this.config.compactionKeepRecent,
-                        });
-                        if (result.droppedCount > 0) {
-                            messages.length = 0;
-                            for (const m of result.messages)
-                                messages.push(m);
-                            masker?.reset(); // the history was replaced, so the frozen boundary no longer applies
-                            // A mid-run steering doc summarized away may be injected again on the next touch.
-                            for (const name of [...steeringInMessages]) {
-                                const marker = `<steering name="${name}">`;
-                                if (messages.some((m) => typeof m.content === 'string' && m.content.includes(marker)))
-                                    continue;
-                                steeringInMessages.delete(name);
-                                steeringInjected.delete(name);
-                                steeringInjections--;
-                            }
-                            emit({
-                                type: 'compaction',
-                                droppedCount: result.droppedCount,
-                                savedTokens: result.savedTokens,
-                                summary: result.summary,
-                            });
-                        }
+                    const totalForNextTurn = Math.max(lastTurnInputTokens, estimateMessageTokens(messages));
+                    if (shouldCompactForBudget(totalForNextTurn, currentModelConfig, threshold, this.config.contextBudgetTokens)) {
+                        await compactNow(totalForNextTurn);
                     }
                 }
             }
@@ -809,29 +1038,31 @@ export class Agent {
             else {
                 reason = 'error';
                 const message = errorMessageOf(err);
-                if (reportedStreamError && /^No output generated/i.test(message)) {
-                    // The SDK follows a failed call with this generic error; the first one is the useful one.
-                    errorMessage = reportedStreamError;
-                }
-                else {
-                    errorMessage = message;
-                    emit({ type: 'error', error: errorMessage });
-                }
+                // The SDK follows a failed call with this generic error; the first one is the useful one.
+                errorMessage = reportedStreamError && /^No output generated/i.test(message) ? reportedStreamError : message;
+                emit({ type: 'error', error: errorMessage });
             }
         }
         // A run that ends between pushing the continue message and sending it (stop, timeout)
         // must not hand that unanswered message back as history.
         const lastMessage = messages[messages.length - 1];
         if (continuedText !== '' && lastMessage?.role === 'user' && lastMessage.content === CONTINUE_PROMPT)
-            messages.pop();
+            unappend();
+        else if (todoNudgeMessage && lastMessage === todoNudgeMessage)
+            unappend();
         // Stopped mid-answer: keep the part the user already saw, marked as cut short, so "continue" can pick it up
         // instead of starting over. Only when the model is the next speaker (after the user or a tool result).
         if (reason === 'aborted' && partialStepText.trim()) {
             const last = messages[messages.length - 1];
             if (last && (last.role === 'user' || last.role === 'tool')) {
-                messages.push({ role: 'assistant', content: `${partialStepText.trim()}\n\n[Stopped by the user before finishing.]` });
+                append({ role: 'assistant', content: `${partialStepText.trim()}\n\n[Stopped by the user before finishing.]` });
             }
         }
+        // Background processes belong to the run: stop what is still going and say so in the answer.
+        const leftRunning = ctx.processes?.stopAll() ?? [];
+        if (leftRunning.length > 0) {
+            finalText += `${finalText ? '\n\n' : ''}[Stopped ${leftRunning.length} background process${leftRunning.length === 1 ? '' : 'es'} when this run ended: ${leftRunning.map((p) => p.command).join(', ')}]`;
+        }
         // The browser is per-run: never leave a Chrome process behind.
         await this.browser?.close().catch(() => undefined);
         emit({ type: 'done', reason });
@@ -855,6 +1086,7 @@ export class Agent {
             // Snapshot of the final conversation: the REPL passes this back as
             // the `history` argument on the next turn so context persists.
             messages: messages.slice(),
+            turnMessages: turnMessages.slice(),
             ...(verification ? { verification } : {}),
             ...(errorMessage ? { error: errorMessage } : {}),
         };
@@ -981,23 +1213,23 @@ export class Agent {
         if (rule?.action === 'deny')
             return { approved: false, note: rule.reason };
         if (rule?.action === 'allow')
-            return { approved: true };
+            return { approved: true, source: 'rule' };
         const forceAsk = rule?.action === 'ask';
         // Read-only tools the user chose not to be asked about (never a destructive one).
         if (!forceAsk && !def.destructive && this.config.autoApproveTools?.includes(def.name)) {
-            return { approved: true };
+            return { approved: true, source: 'list' };
         }
         // Memory writes the user chose not to be asked about. memory_forget is deleted data: always asked.
         if (!forceAsk && def.name === 'memory_write' && this.config.memoryAutoApproveWrites) {
-            return { approved: true };
+            return { approved: true, source: 'memory' };
         }
         // A plain command the user already said "always allow" for: exact match only (see command-allow.ts).
         if (!forceAsk && def.name === 'run_command' && this.config.autoApproveCommands?.length && isListedCommand(args, this.config.autoApproveCommands)) {
-            return { approved: true };
+            return { approved: true, source: 'always' };
         }
         const auto = this.config.auto ?? false;
         if (!forceAsk && auto && !(def.destructive && !this.config.allowDestructive)) {
-            return { approved: true };
+            return { approved: true, source: 'autonomous' };
         }
         let preview;
         if (def.previewApproval && ctx) {
@@ -1025,7 +1257,8 @@ export class Agent {
             const decision = await raceAbort(answered, abortSignal, 'aborted');
             if (decision === 'aborted')
                 return { approved: false };
-            return typeof decision === 'boolean' ? { approved: decision } : decision;
+            const answer = typeof decision === 'boolean' ? { approved: decision } : decision;
+            return answer.approved ? { ...answer, source: 'person' } : answer;
         }
         return { approved: false };
     }
@@ -1103,7 +1336,9 @@ function extractMediaAttachment(result) {
     const bytes = typeof r.bytes === 'number' ? r.bytes : 0;
     const path = typeof r.path === 'string' ? r.path : '<unknown>';
     const what = mime.startsWith('image/') ? 'Image' : 'Document';
-    const summary = `${what} attached: ${mime} (${formatBytes(bytes)}) at ${path}`;
+    // A tool that sends words with its media (an MCP result) keeps them next to the attachment line.
+    const words = typeof r.text === 'string' && r.text.trim() ? `\n${r.text}` : '';
+    const summary = `${what} attached: ${mime} (${formatBytes(bytes)}) at ${path}${words}`;
     const comma = dataUrl.indexOf(',');
     const filename = typeof r.path === 'string' ? r.path.split(/[\\/]/).pop() : undefined;
     return { dataUrl, base64: dataUrl.slice(comma + 1), mime, ...(filename ? { filename } : {}), summary };
@@ -1142,15 +1377,14 @@ export function applySandbox(tools, sandbox) {
     return result;
 }
 /**
- * Build the initial `[system, user]` messages for a fresh run. If memory
- * is enabled and a `.forge/MEMORY.md` exists somewhere up the cwd tree, we
- * append a `<project-memory>...</project-memory>` block to the system
- * prompt so the agent picks up project conventions on turn one.
+ * Build the system message for a run, on every turn (RB-57). If memory is enabled and a `.forge/MEMORY.md` exists
+ * somewhere up the cwd tree, a `<project-memory>...</project-memory>` block is appended so the agent picks up project
+ * conventions.
  *
  * This is async because memory loading hits the disk. When memory is
  * disabled or no file exists, this is a fast synchronous-feeling path.
  */
-async function buildInitialMessages(config, task, skills, steeringSystem = [], userContent = task) {
+async function buildSystemContent(config, task, skills, steeringSystem = []) {
     let basePrompt = config.systemPrompt ?? DEFAULT_SYSTEM_PROMPT;
     if (config.planMode) {
         basePrompt = basePrompt + (config.planModePrompt ?? DEFAULT_PLAN_MODE_SUFFIX);
@@ -1176,7 +1410,8 @@ async function buildInitialMessages(config, task, skills, steeringSystem = [], u
         try {
             const all = skills.registry.list();
             const selected = selectSkills(all, task, skills.maxSkills ?? 3);
-            skillsBlock = composeSkillsPrompt(selected);
+            // The index of every skill (G12) comes first and is the same every turn; the picked bodies follow.
+            skillsBlock = [buildSkillIndex(all), composeSkillsPrompt(selected)].filter(Boolean).join('\n\n');
         }
         catch {
             // Skill selection failure shouldn't kill a run: just skip.
@@ -1209,12 +1444,7 @@ async function buildInitialMessages(config, task, skills, steeringSystem = [], u
             // A map failure shouldn't kill a run: just skip.
         }
     }
-    // Interview answers from a guided journey. This function runs only when no
-    // history is passed (see the `options.history` branch in `run`), so every
-    // block here is assembled once, on a session's first turn, and then rides
-    // inside `history[0]`. That is why a journey's interview must finish before
-    // the first run: an answer that arrives on turn 3 can never enter the system
-    // message, and a middle turn would be summarised away by compaction.
+    // Interview answers from a guided journey. Rebuilt with the rest of the system message on every turn (RB-57).
     const answersBlock = renderAnswersBlock(config.journeyAnswers ?? []);
     // The versions the workspace's files state, so code is written for them and not for what training saw most.
     let stackFactsBlock = '';
@@ -1235,42 +1465,14 @@ async function buildInitialMessages(config, task, skills, steeringSystem = [], u
         isGitRepo: existsSync(path.join(cwd, '.git')),
         today: new Date().toISOString().slice(0, 10),
         model: config.model?.model,
+        // A custom runner (the VS Code terminal) says which shell it is; Forge's own runner picks one itself.
+        ...(config.runnerShell ? { shell: config.runnerShell } : config.commandRunner ? {} : { shell: runnerShell(config.shell).kind }),
     });
     // Compose the final system prompt: base + (memory, skills) blocks in a
     // stable order so cache hits survive across runs that share state. The
     // environment block goes last: it is the part that varies per session.
     const steeringBlock = steeringSystem.map(wrapSteering).join('\n\n');
-    const blocks = [steeringBlock, instructionsBlock, extraInstructionsBlock, config.mcpInstructions ?? '', config.projectCommands ?? '', memoryBlock, skillsBlock, answersBlock, mapBlock, stackFactsBlock, envBlock].filter((b) => b.length > 0);
-    const systemContent = blocks.length > 0 ? `${basePrompt}\n\n${blocks.join('\n\n')}` : basePrompt;
-    return [
-        { role: 'system', content: systemContent },
-        { role: 'user', content: userContent },
-    ];
-}
-/**
- * Rough estimate of the next-turn prompt size from the message list.
- * Used to decide whether to compact before the next model call. We use
- * `Math.ceil(text.length / 4)` (≈ OpenAI's tokenizer behavior): good
- * enough for "are we close to the window?" decisions.
- */
-function estimateNextPromptTokens(messages) {
-    let total = 0;
-    for (const m of messages) {
-        if (typeof m.content === 'string') {
-            total += Math.ceil(m.content.length / 4);
-        }
-        else if (Array.isArray(m.content)) {
-            for (const part of m.content) {
-                if (part && typeof part === 'object' && 'text' in part) {
-                    const text = part.text;
-                    if (typeof text === 'string')
-                        total += Math.ceil(text.length / 4);
-                }
-                else {
-                    total += mediaPartTokens(part);
-                }
-            }
-        }
-    }
-    return total;
+    const guidanceBlock = config.model ? modelGuidanceBlock(config.model) : '';
+    const blocks = [steeringBlock, instructionsBlock, extraInstructionsBlock, config.mcpInstructions ?? '', config.projectCommands ?? '', memoryBlock, skillsBlock, answersBlock, mapBlock, stackFactsBlock, guidanceBlock, envBlock].filter((b) => b.length > 0);
+    return blocks.length > 0 ? `${basePrompt}\n\n${blocks.join('\n\n')}` : basePrompt;
 }