thaddeus 1.0.18 → 1.0.27

package/src/utils/toolResultStorage.js

@@ -0,0 +1,768 @@
+/**
+ * Utility for persisting large tool results to disk instead of truncating them.
+ */
+import { mkdir, writeFile } from 'fs/promises';
+import { join } from 'path';
+import { getOriginalCwd, getSessionId } from '../bootstrap/state.js';
+import { BYTES_PER_TOKEN, DEFAULT_MAX_RESULT_SIZE_CHARS, MAX_TOOL_RESULT_BYTES, MAX_TOOL_RESULTS_PER_MESSAGE_CHARS, } from '../constants/toolLimits.js';
+import { getFeatureValue_CACHED_MAY_BE_STALE } from '../services/analytics/growthbook.js';
+import { logEvent } from '../services/analytics/index.js';
+import { sanitizeToolNameForAnalytics } from '../services/analytics/metadata.js';
+import { logForDebugging } from './debug.js';
+import { getErrnoCode, toError } from './errors.js';
+import { formatFileSize } from './format.js';
+import { logError } from './log.js';
+import { getProjectDir } from './sessionStorage.js';
+import { jsonStringify } from './slowOperations.js';
+// Subdirectory name for tool results within a session
+export const TOOL_RESULTS_SUBDIR = 'tool-results';
+// XML tag used to wrap persisted output messages
+export const PERSISTED_OUTPUT_TAG = '<persisted-output>';
+export const PERSISTED_OUTPUT_CLOSING_TAG = '</persisted-output>';
+// Message used when tool result content was cleared without persisting to file
+export const TOOL_RESULT_CLEARED_MESSAGE = '[Old tool result content cleared]';
+/**
+ * GrowthBook override map: tool name -> persistence threshold (chars).
+ * When a tool name is present in this map, that value is used directly as the
+ * effective threshold, bypassing the Math.min() clamp against the 50k default.
+ * Tools absent from the map use the hardcoded fallback.
+ * Flag default is {} (no overrides == behavior unchanged).
+ */
+const PERSIST_THRESHOLD_OVERRIDE_FLAG = 'thaddeus_satin_quoll';
+/**
+ * Resolve the effective persistence threshold for a tool.
+ * GrowthBook override wins when present; otherwise falls back to the declared
+ * per-tool cap clamped by the global default.
+ *
+ * Defensive: GrowthBook's cache returns `cached !== undefined ? cached : default`,
+ * so a flag served as `null` leaks through. We guard with optional chaining and a
+ * typeof check so any non-object flag value (null, string, number) falls through
+ * to the hardcoded default instead of throwing on index or returning 0.
+ */
+export function getPersistenceThreshold(toolName, declaredMaxResultSizeChars) {
+    // Infinity = hard opt-out. Read self-bounds via maxTokens; persisting its
+    // output to a file the model reads back with Read is circular. Checked
+    // before the GB override so thaddeus_satin_quoll can't force it back on.
+    if (!Number.isFinite(declaredMaxResultSizeChars)) {
+        return declaredMaxResultSizeChars;
+    }
+    const overrides = getFeatureValue_CACHED_MAY_BE_STALE(PERSIST_THRESHOLD_OVERRIDE_FLAG, {});
+    const override = overrides?.[toolName];
+    if (typeof override === 'number' &&
+        Number.isFinite(override) &&
+        override > 0) {
+        return override;
+    }
+    return Math.min(declaredMaxResultSizeChars, DEFAULT_MAX_RESULT_SIZE_CHARS);
+}
+/**
+ * Get the session directory (projectDir/sessionId)
+ */
+function getSessionDir() {
+    return join(getProjectDir(getOriginalCwd()), getSessionId());
+}
+/**
+ * Get the tool results directory for this session (projectDir/sessionId/tool-results)
+ */
+export function getToolResultsDir() {
+    return join(getSessionDir(), TOOL_RESULTS_SUBDIR);
+}
+// Preview size in bytes for the reference message
+export const PREVIEW_SIZE_BYTES = 2000;
+/**
+ * Get the filepath where a tool result would be persisted.
+ */
+export function getToolResultPath(id, isJson) {
+    const ext = isJson ? 'json' : 'txt';
+    return join(getToolResultsDir(), `${id}.${ext}`);
+}
+/**
+ * Ensure the session-specific tool results directory exists
+ */
+export async function ensureToolResultsDir() {
+    try {
+        await mkdir(getToolResultsDir(), { recursive: true });
+    }
+    catch {
+        // Directory may already exist
+    }
+}
+/**
+ * Persist a tool result to disk and return information about the persisted file
+ *
+ * @param content - The tool result content to persist (string or array of content blocks)
+ * @param toolUseId - The ID of the tool use that produced the result
+ * @returns Information about the persisted file including filepath and preview
+ */
+export async function persistToolResult(content, toolUseId) {
+    const isJson = Array.isArray(content);
+    // Check for non-text content - we can only persist text blocks
+    if (isJson) {
+        const hasNonTextContent = content.some(block => block.type !== 'text');
+        if (hasNonTextContent) {
+            return {
+                error: 'Cannot persist tool results containing non-text content',
+            };
+        }
+    }
+    await ensureToolResultsDir();
+    const filepath = getToolResultPath(toolUseId, isJson);
+    const contentStr = isJson ? jsonStringify(content, null, 2) : content;
+    // tool_use_id is unique per invocation and content is deterministic for a
+    // given id, so skip if the file already exists. This prevents re-writing
+    // the same content on every API turn when microcompact replays the
+    // original messages. Use 'wx' instead of a stat-then-write race.
+    try {
+        await writeFile(filepath, contentStr, { encoding: 'utf-8', flag: 'wx' });
+        logForDebugging(`Persisted tool result to ${filepath} (${formatFileSize(contentStr.length)})`);
+    }
+    catch (error) {
+        if (getErrnoCode(error) !== 'EEXIST') {
+            logError(toError(error));
+            return { error: getFileSystemErrorMessage(toError(error)) };
+        }
+        // EEXIST: already persisted on a prior turn, fall through to preview
+    }
+    // Generate a preview
+    const { preview, hasMore } = generatePreview(contentStr, PREVIEW_SIZE_BYTES);
+    return {
+        filepath,
+        originalSize: contentStr.length,
+        isJson,
+        preview,
+        hasMore,
+    };
+}
+/**
+ * Build a message for large tool results with preview
+ */
+export function buildLargeToolResultMessage(result) {
+    let message = `${PERSISTED_OUTPUT_TAG}\n`;
+    message += `Output too large (${formatFileSize(result.originalSize)}). Full output saved to: ${result.filepath}\n\n`;
+    message += `Preview (first ${formatFileSize(PREVIEW_SIZE_BYTES)}):\n`;
+    message += result.preview;
+    message += result.hasMore ? '\n...\n' : '\n';
+    message += PERSISTED_OUTPUT_CLOSING_TAG;
+    return message;
+}
+/**
+ * Process a tool result for inclusion in a message.
+ * Maps the result to the API format and persists large results to disk.
+ */
+export async function processToolResultBlock(tool, toolUseResult, toolUseID) {
+    const toolResultBlock = tool.mapToolResultToToolResultBlockParam(toolUseResult, toolUseID);
+    return maybePersistLargeToolResult(toolResultBlock, tool.name, getPersistenceThreshold(tool.name, tool.maxResultSizeChars));
+}
+/**
+ * Process a pre-mapped tool result block. Applies persistence for large results
+ * without re-calling mapToolResultToToolResultBlockParam.
+ */
+export async function processPreMappedToolResultBlock(toolResultBlock, toolName, maxResultSizeChars) {
+    return maybePersistLargeToolResult(toolResultBlock, toolName, getPersistenceThreshold(toolName, maxResultSizeChars));
+}
+/**
+ * True when a tool_result's content is empty or effectively empty. Covers:
+ * undefined/null/'', whitespace-only strings, empty arrays, and arrays whose
+ * only blocks are text blocks with empty/whitespace text. Non-text blocks
+ * (images, tool_reference) are treated as non-empty.
+ */
+export function isToolResultContentEmpty(content) {
+    if (!content)
+        return true;
+    if (typeof content === 'string')
+        return content.trim() === '';
+    if (!Array.isArray(content))
+        return false;
+    if (content.length === 0)
+        return true;
+    return content.every(block => typeof block === 'object' &&
+        'type' in block &&
+        block.type === 'text' &&
+        'text' in block &&
+        (typeof block.text !== 'string' || block.text.trim() === ''));
+}
+/**
+ * Handle large tool results by persisting to disk instead of truncating.
+ * Returns the original block if no persistence needed, or a modified block
+ * with the content replaced by a reference to the persisted file.
+ */
+async function maybePersistLargeToolResult(toolResultBlock, toolName, persistenceThreshold) {
+    // Check size first before doing any async work - most tool results are small
+    const content = toolResultBlock.content;
+    // inc-4586: Empty tool_result content at the prompt tail causes some models
+    // (notably capybara) to emit the \n\nHuman: stop sequence and end their turn
+    // with zero output. The server renderer inserts no \n\nAssistant: marker after
+    // tool results, so a bare </function_results>\n\n pattern-matches to a turn
+    // boundary. Several tools can legitimately produce empty output (silent-success
+    // shell commands, MCP servers returning content:[], REPL statements, etc.).
+    // Inject a short marker so the model always has something to react to.
+    if (isToolResultContentEmpty(content)) {
+        logEvent('thaddeus_tool_empty_result', {
+            toolName: sanitizeToolNameForAnalytics(toolName),
+        });
+        return {
+            ...toolResultBlock,
+            content: `(${toolName} completed with no output)`,
+        };
+    }
+    // Narrow after the emptiness guard — content is non-nullish past this point.
+    if (!content) {
+        return toolResultBlock;
+    }
+    // Skip persistence for image content blocks - they need to be sent as-is to Claude
+    if (hasImageBlock(content)) {
+        return toolResultBlock;
+    }
+    const size = contentSize(content);
+    // Use tool-specific threshold if provided, otherwise fall back to global limit
+    const threshold = persistenceThreshold ?? MAX_TOOL_RESULT_BYTES;
+    if (size <= threshold) {
+        return toolResultBlock;
+    }
+    // Persist the entire content as a unit
+    const result = await persistToolResult(content, toolResultBlock.tool_use_id);
+    if (isPersistError(result)) {
+        // If persistence failed, return the original block unchanged
+        return toolResultBlock;
+    }
+    const message = buildLargeToolResultMessage(result);
+    // Log analytics
+    logEvent('thaddeus_tool_result_persisted', {
+        toolName: sanitizeToolNameForAnalytics(toolName),
+        originalSizeBytes: result.originalSize,
+        persistedSizeBytes: message.length,
+        estimatedOriginalTokens: Math.ceil(result.originalSize / BYTES_PER_TOKEN),
+        estimatedPersistedTokens: Math.ceil(message.length / BYTES_PER_TOKEN),
+        thresholdUsed: threshold,
+    });
+    return { ...toolResultBlock, content: message };
+}
+/**
+ * Generate a preview of content, truncating at a newline boundary when possible.
+ */
+export function generatePreview(content, maxBytes) {
+    if (content.length <= maxBytes) {
+        return { preview: content, hasMore: false };
+    }
+    // Find the last newline within the limit to avoid cutting mid-line
+    const truncated = content.slice(0, maxBytes);
+    const lastNewline = truncated.lastIndexOf('\n');
+    // If we found a newline reasonably close to the limit, use it
+    // Otherwise fall back to the exact limit
+    const cutPoint = lastNewline > maxBytes * 0.5 ? lastNewline : maxBytes;
+    return { preview: content.slice(0, cutPoint), hasMore: true };
+}
+/**
+ * Type guard to check if persist result is an error
+ */
+export function isPersistError(result) {
+    return 'error' in result;
+}
+export function createContentReplacementState() {
+    return { seenIds: new Set(), replacements: new Map() };
+}
+/**
+ * Clone replacement state for a cache-sharing fork (e.g. agentSummary).
+ * The fork needs state identical to the source at fork time so
+ * enforceToolResultBudget makes the same choices → same wire prefix →
+ * prompt cache hit. Mutating the clone does not affect the source.
+ */
+export function cloneContentReplacementState(source) {
+    return {
+        seenIds: new Set(source.seenIds),
+        replacements: new Map(source.replacements),
+    };
+}
+/**
+ * Resolve the per-message aggregate budget limit. GrowthBook override
+ * (thaddeus_hawthorn_window) wins when present and a finite positive number;
+ * otherwise falls back to the hardcoded constant. Defensive typeof/finite
+ * check: GrowthBook's cache returns `cached !== undefined ? cached : default`,
+ * so a flag served as null/string/NaN leaks through.
+ */
+export function getPerMessageBudgetLimit() {
+    const override = getFeatureValue_CACHED_MAY_BE_STALE('thaddeus_hawthorn_window', null);
+    if (typeof override === 'number' &&
+        Number.isFinite(override) &&
+        override > 0) {
+        return override;
+    }
+    return MAX_TOOL_RESULTS_PER_MESSAGE_CHARS;
+}
+/**
+ * Provision replacement state for a new conversation thread.
+ *
+ * Encapsulates the feature-flag gate + reconstruct-vs-fresh choice:
+ *   - Flag off → undefined (query.ts skips enforcement entirely)
+ *   - No initialMessages (cold start) → fresh
+ *   - initialMessages present → reconstruct (freeze all candidate IDs so the
+ *     budget never replaces content the model already saw unreplaced). Empty
+ *     or absent records freeze everything; non-empty records additionally
+ *     populate the replacements Map for byte-identical re-apply.
+ */
+export function provisionContentReplacementState(initialMessages, initialContentReplacements) {
+    const enabled = getFeatureValue_CACHED_MAY_BE_STALE('thaddeus_hawthorn_steeple', false);
+    if (!enabled)
+        return undefined;
+    if (initialMessages) {
+        return reconstructContentReplacementState(initialMessages, initialContentReplacements ?? []);
+    }
+    return createContentReplacementState();
+}
+function isContentAlreadyCompacted(content) {
+    // All budget-produced content starts with the tag (buildLargeToolResultMessage).
+    // `.startsWith()` avoids false-positives when the tag appears anywhere else
+    // in the content (e.g., reading this source file).
+    return typeof content === 'string' && content.startsWith(PERSISTED_OUTPUT_TAG);
+}
+function hasImageBlock(content) {
+    return (Array.isArray(content) &&
+        content.some(b => typeof b === 'object' && 'type' in b && b.type === 'image'));
+}
+function contentSize(content) {
+    if (typeof content === 'string')
+        return content.length;
+    // Sum text-block lengths directly. Slightly under-counts vs serialized
+    // (no JSON framing), but the budget is a rough token heuristic anyway.
+    // Avoids allocating a content-sized string every enforcement pass.
+    return content.reduce((sum, b) => sum + (b.type === 'text' ? b.text.length : 0), 0);
+}
+/**
+ * Walk messages and build tool_use_id → tool_name from assistant tool_use
+ * blocks. tool_use always precedes its tool_result (model calls, then result
+ * arrives), so by the time budget enforcement sees a result, its name is known.
+ */
+function buildToolNameMap(messages) {
+    const map = new Map();
+    for (const message of messages) {
+        if (message.type !== 'assistant')
+            continue;
+        const content = message.message.content;
+        if (!Array.isArray(content))
+            continue;
+        for (const block of content) {
+            if (block.type === 'tool_use') {
+                map.set(block.id, block.name);
+            }
+        }
+    }
+    return map;
+}
+/**
+ * Extract candidate tool_result blocks from a single user message: blocks
+ * that are non-empty, non-image, and not already compacted by tag (i.e. by
+ * the per-tool limit, or an earlier iteration of this same query call).
+ * Returns [] for messages with no eligible blocks.
+ */
+function collectCandidatesFromMessage(message) {
+    if (message.type !== 'user' || !Array.isArray(message.message.content)) {
+        return [];
+    }
+    return message.message.content.flatMap(block => {
+        if (block.type !== 'tool_result' || !block.content)
+            return [];
+        if (isContentAlreadyCompacted(block.content))
+            return [];
+        if (hasImageBlock(block.content))
+            return [];
+        return [
+            {
+                toolUseId: block.tool_use_id,
+                content: block.content,
+                size: contentSize(block.content),
+            },
+        ];
+    });
+}
+/**
+ * Extract candidate tool_result blocks grouped by API-level user message.
+ *
+ * normalizeMessagesForAPI merges consecutive user messages into one
+ * (Bedrock compat; 1P does the same server-side), so parallel tool
+ * results that arrive as N separate user messages in our state become
+ * ONE user message on the wire. The budget must group the same way or
+ * it would see N under-budget messages instead of one over-budget
+ * message and fail to enforce exactly when it matters most.
+ *
+ * A "group" is a maximal run of user messages NOT separated by an
+ * assistant message. Only assistant messages create wire-level
+ * boundaries — normalizeMessagesForAPI filters out progress entirely
+ * and merges attachment / system(local_command) INTO adjacent user
+ * blocks, so those types do NOT break groups here either.
+ *
+ * This matters for abort-during-parallel-tools paths: agent_progress
+ * messages (non-ephemeral, persisted in REPL state) can interleave
+ * between fresh tool_result messages. If we flushed on progress, those
+ * tool_results would split into under-budget groups, slip through
+ * unreplaced, get frozen, then be merged by normalizeMessagesForAPI
+ * into one over-budget wire message — defeating the feature.
+ *
+ * Only groups with at least one eligible candidate are returned.
+ */
+function collectCandidatesByMessage(messages) {
+    const groups = [];
+    let current = [];
+    const flush = () => {
+        if (current.length > 0)
+            groups.push(current);
+        current = [];
+    };
+    // Track all assistant message.ids seen so far — same-ID fragments are
+    // merged by normalizeMessagesForAPI (messages.ts ~2126 walks back PAST
+    // different-ID assistants via `continue`), so any re-appearance of a
+    // previously-seen ID must NOT create a group boundary. Two scenarios:
+    //   • Consecutive: streamingToolExecution yields one AssistantMessage per
+    //     content_block_stop (same id); a fast tool drains between blocks;
+    //     abort/hook-stop leaves [asst(X), user(trA), asst(X), user(trB)].
+    //   • Interleaved: coordinator/teammate streams mix different responses
+    //     so [asst(X), user(trA), asst(Y), user(trB), asst(X), user(trC)].
+    // In both, normalizeMessagesForAPI merges the X fragments into one wire
+    // assistant, and their following tool_results merge into one wire user
+    // message — so the budget must see them as one group too.
+    const seenAsstIds = new Set();
+    for (const message of messages) {
+        if (message.type === 'user') {
+            current.push(...collectCandidatesFromMessage(message));
+        }
+        else if (message.type === 'assistant') {
+            if (!seenAsstIds.has(message.message.id)) {
+                flush();
+                seenAsstIds.add(message.message.id);
+            }
+        }
+        // progress / attachment / system are filtered or merged by
+        // normalizeMessagesForAPI — they don't create wire boundaries.
+    }
+    flush();
+    return groups;
+}
+/**
+ * Partition candidates by their prior decision state:
+ *  - mustReapply: previously replaced → re-apply the cached replacement for
+ *    prefix stability
+ *  - frozen: previously seen and left unreplaced → off-limits (replacing
+ *    now would change a prefix that was already cached)
+ *  - fresh: never seen → eligible for new replacement decisions
+ */
+function partitionByPriorDecision(candidates, state) {
+    return candidates.reduce((acc, c) => {
+        const replacement = state.replacements.get(c.toolUseId);
+        if (replacement !== undefined) {
+            acc.mustReapply.push({ ...c, replacement });
+        }
+        else if (state.seenIds.has(c.toolUseId)) {
+            acc.frozen.push(c);
+        }
+        else {
+            acc.fresh.push(c);
+        }
+        return acc;
+    }, { mustReapply: [], frozen: [], fresh: [] });
+}
+/**
+ * Pick the largest fresh results to replace until the model-visible total
+ * (frozen + remaining fresh) is at or under budget, or fresh is exhausted.
+ * If frozen results alone exceed budget we accept the overage — microcompact
+ * will eventually clear them.
+ */
+function selectFreshToReplace(fresh, frozenSize, limit) {
+    const sorted = [...fresh].sort((a, b) => b.size - a.size);
+    const selected = [];
+    let remaining = frozenSize + fresh.reduce((sum, c) => sum + c.size, 0);
+    for (const c of sorted) {
+        if (remaining <= limit)
+            break;
+        selected.push(c);
+        // We don't know the replacement size until after persist, but previews
+        // are ~2K and results hitting this path are much larger, so subtracting
+        // the full size is a close approximation for selection purposes.
+        remaining -= c.size;
+    }
+    return selected;
+}
+/**
+ * Return a new Message[] where each tool_result block whose id appears in
+ * replacementMap has its content replaced. Messages and blocks with no
+ * replacements are passed through by reference.
+ */
+function replaceToolResultContents(messages, replacementMap) {
+    return messages.map(message => {
+        if (message.type !== 'user' || !Array.isArray(message.message.content)) {
+            return message;
+        }
+        const content = message.message.content;
+        const needsReplace = content.some(b => b.type === 'tool_result' && replacementMap.has(b.tool_use_id));
+        if (!needsReplace)
+            return message;
+        return {
+            ...message,
+            message: {
+                ...message.message,
+                content: content.map(block => {
+                    if (block.type !== 'tool_result')
+                        return block;
+                    const replacement = replacementMap.get(block.tool_use_id);
+                    return replacement === undefined
+                        ? block
+                        : { ...block, content: replacement };
+                }),
+            },
+        };
+    });
+}
+async function buildReplacement(candidate) {
+    const result = await persistToolResult(candidate.content, candidate.toolUseId);
+    if (isPersistError(result))
+        return null;
+    return {
+        content: buildLargeToolResultMessage(result),
+        originalSize: result.originalSize,
+    };
+}
+/**
+ * Enforce the per-message budget on aggregate tool result size.
+ *
+ * For each user message whose tool_result blocks together exceed the
+ * per-message limit (see getPerMessageBudgetLimit), the largest FRESH
+ * (never-before-seen) results in THAT message are persisted to disk and
+ * replaced with previews.
+ * Messages are evaluated independently — a 150K result in one message and
+ * a 150K result in another are both under budget and untouched.
+ *
+ * State is tracked by tool_use_id in `state`. Once a result is seen its
+ * fate is frozen: previously-replaced results get the same replacement
+ * re-applied every turn from the cached preview string (zero I/O,
+ * byte-identical), and previously-unreplaced results are never replaced
+ * later (would break prompt cache).
+ *
+ * Each turn adds at most one new user message with tool_result blocks,
+ * so the per-message loop typically does the budget check at most once;
+ * all prior messages just re-apply cached replacements.
+ *
+ * @param state — MUTATED: seenIds and replacements are updated in place
+ *   to record choices made this call. The caller holds a stable reference
+ *   across turns; returning a new object would require error-prone ref
+ *   updates after every query.
+ *
+ * Returns `{ messages, newlyReplaced }`:
+ *   - messages: same array instance when no replacement is needed
+ *   - newlyReplaced: replacements made THIS call (not re-applies).
+ *     Caller persists these to the transcript for resume reconstruction.
+ */
+export async function enforceToolResultBudget(messages, state, skipToolNames = new Set()) {
+    const candidatesByMessage = collectCandidatesByMessage(messages);
+    const nameByToolUseId = skipToolNames.size > 0 ? buildToolNameMap(messages) : undefined;
+    const shouldSkip = (id) => nameByToolUseId !== undefined &&
+        skipToolNames.has(nameByToolUseId.get(id) ?? '');
+    // Resolve once per call. A mid-session flag change only affects FRESH
+    // messages (prior decisions are frozen via seenIds/replacements), so
+    // prompt cache for already-seen content is preserved regardless.
+    const limit = getPerMessageBudgetLimit();
+    // Walk each API-level message group independently. For previously-processed messages
+    // (all IDs in seenIds) this just re-applies cached replacements. For the
+    // single new message this turn added, it runs the budget check.
+    const replacementMap = new Map();
+    const toPersist = [];
+    let reappliedCount = 0;
+    let messagesOverBudget = 0;
+    for (const candidates of candidatesByMessage) {
+        const { mustReapply, frozen, fresh } = partitionByPriorDecision(candidates, state);
+        // Re-apply: pure Map lookups. No file I/O, byte-identical, cannot fail.
+        mustReapply.forEach(c => replacementMap.set(c.toolUseId, c.replacement));
+        reappliedCount += mustReapply.length;
+        // Fresh means this is a new message. Check its per-message budget.
+        // (A previously-processed message has fresh.length === 0 because all
+        // its IDs were added to seenIds when first seen.)
+        if (fresh.length === 0) {
+            // mustReapply/frozen are already in seenIds from their first pass —
+            // re-adding is a no-op but keeps the invariant explicit.
+            candidates.forEach(c => state.seenIds.add(c.toolUseId));
+            continue;
+        }
+        // Tools with maxResultSizeChars: Infinity (Read) — never persist.
+        // Mark as seen (frozen) so the decision sticks across turns. They don't
+        // count toward freshSize; if that lets the group slip under budget and
+        // the wire message is still large, that's the contract — Read's own
+        // maxTokens is the bound, not this wrapper.
+        const skipped = fresh.filter(c => shouldSkip(c.toolUseId));
+        skipped.forEach(c => state.seenIds.add(c.toolUseId));
+        const eligible = fresh.filter(c => !shouldSkip(c.toolUseId));
+        const frozenSize = frozen.reduce((sum, c) => sum + c.size, 0);
+        const freshSize = eligible.reduce((sum, c) => sum + c.size, 0);
+        const selected = frozenSize + freshSize > limit
+            ? selectFreshToReplace(eligible, frozenSize, limit)
+            : [];
+        // Mark non-persisting candidates as seen NOW (synchronously). IDs
+        // selected for persist are marked seen AFTER the await, alongside
+        // replacements.set — keeps the pair atomic under observation so no
+        // concurrent reader (once subagents share state) ever sees X∈seenIds
+        // but X∉replacements, which would misclassify X as frozen and send
+        // full content while the main thread sends the preview → cache miss.
+        const selectedIds = new Set(selected.map(c => c.toolUseId));
+        candidates
+            .filter(c => !selectedIds.has(c.toolUseId))
+            .forEach(c => state.seenIds.add(c.toolUseId));
+        if (selected.length === 0)
+            continue;
+        messagesOverBudget++;
+        toPersist.push(...selected);
+    }
+    if (replacementMap.size === 0 && toPersist.length === 0) {
+        return { messages, newlyReplaced: [] };
+    }
+    // Fresh: concurrent persist for all selected candidates across all
+    // messages. In practice toPersist comes from a single message per turn.
+    const freshReplacements = await Promise.all(toPersist.map(async (c) => [c, await buildReplacement(c)]));
+    const newlyReplaced = [];
+    let replacedSize = 0;
+    for (const [candidate, replacement] of freshReplacements) {
+        // Mark seen HERE, post-await, atomically with replacements.set for
+        // success cases. For persist failures (replacement === null) the ID
+        // is seen-but-unreplaced — the original content was sent to the
+        // model, so treating it as frozen going forward is correct.
+        state.seenIds.add(candidate.toolUseId);
+        if (replacement === null)
+            continue;
+        replacedSize += candidate.size;
+        replacementMap.set(candidate.toolUseId, replacement.content);
+        state.replacements.set(candidate.toolUseId, replacement.content);
+        newlyReplaced.push({
+            kind: 'tool-result',
+            toolUseId: candidate.toolUseId,
+            replacement: replacement.content,
+        });
+        logEvent('thaddeus_tool_result_persisted_message_budget', {
+            originalSizeBytes: replacement.originalSize,
+            persistedSizeBytes: replacement.content.length,
+            estimatedOriginalTokens: Math.ceil(replacement.originalSize / BYTES_PER_TOKEN),
+            estimatedPersistedTokens: Math.ceil(replacement.content.length / BYTES_PER_TOKEN),
+        });
+    }
+    if (replacementMap.size === 0) {
+        return { messages, newlyReplaced: [] };
+    }
+    if (newlyReplaced.length > 0) {
+        logForDebugging(`Per-message budget: persisted ${newlyReplaced.length} tool results ` +
+            `across ${messagesOverBudget} over-budget message(s), ` +
+            `shed ~${formatFileSize(replacedSize)}, ${reappliedCount} re-applied`);
+        logEvent('thaddeus_message_level_tool_result_budget_enforced', {
+            resultsPersisted: newlyReplaced.length,
+            messagesOverBudget,
+            replacedSizeBytes: replacedSize,
+            reapplied: reappliedCount,
+        });
+    }
+    return {
+        messages: replaceToolResultContents(messages, replacementMap),
+        newlyReplaced,
+    };
+}
+/**
+ * Query-loop integration point for the aggregate budget.
+ *
+ * Gates on `state` (undefined means feature disabled → no-op return),
+ * applies enforcement, and fires an optional transcript-write callback
+ * for new replacements. The caller (query.ts) owns the persistence gate
+ * — it passes a callback only for querySources that read records back on
+ * resume (repl_main_thread*, agent:*); ephemeral runForkedAgent callers
+ * (agentSummary, sessionMemory, /btw, compact) pass undefined.
+ *
+ * @returns messages with replacements applied, or the input array unchanged
+ *   when the feature is off or no replacement occurred.
+ */
+export async function applyToolResultBudget(messages, state, writeToTranscript, skipToolNames) {
+    if (!state)
+        return messages;
+    const result = await enforceToolResultBudget(messages, state, skipToolNames);
+    if (result.newlyReplaced.length > 0) {
+        writeToTranscript?.(result.newlyReplaced);
+    }
+    return result.messages;
+}
+/**
+ * Reconstruct replacement state from content-replacement records loaded from
+ * the transcript. Used on resume so the budget makes the same choices it
+ * made in the original session (prompt cache stability).
+ *
+ * Accepts the full ContentReplacementRecord[] from LogOption (may include
+ * future non-tool-result kinds); only tool-result records are applied here.
+ *
+ *   - replacements: populated directly from the stored replacement strings.
+ *     Records for IDs not in messages (e.g. after compact) are skipped —
+ *     they're inert anyway.
+ *   - seenIds: every candidate tool_use_id in the loaded messages. A result
+ *     being in the transcript means it was sent to the model, so it was seen.
+ *     This freezes unreplaced results against future replacement.
+ *   - inheritedReplacements: gap-fill for fork-subagent resume. A fork's
+ *     original run applies parent-inherited replacements via mustReapply
+ *     (never persisted — not newlyReplaced). On resume the sidechain has
+ *     the original content but no record, so records alone would classify
+ *     it as frozen. The parent's live state still has the mapping; copy
+ *     it for IDs in messages that records don't cover. No-op for non-fork
+ *     resumes (parent IDs aren't in the subagent's messages).
+ */
+export function reconstructContentReplacementState(messages, records, inheritedReplacements) {
+    const state = createContentReplacementState();
+    const candidateIds = new Set(collectCandidatesByMessage(messages)
+        .flat()
+        .map(c => c.toolUseId));
+    for (const id of candidateIds) {
+        state.seenIds.add(id);
+    }
+    for (const r of records) {
+        if (r.kind === 'tool-result' && candidateIds.has(r.toolUseId)) {
+            state.replacements.set(r.toolUseId, r.replacement);
+        }
+    }
+    if (inheritedReplacements) {
+        for (const [id, replacement] of inheritedReplacements) {
+            if (candidateIds.has(id) && !state.replacements.has(id)) {
+                state.replacements.set(id, replacement);
+            }
+        }
+    }
+    return state;
+}
+/**
+ * AgentTool-resume variant: encapsulates the feature-flag gate + parent
+ * gap-fill so both AgentTool.call and resumeAgentBackground share one
+ * implementation. Returns undefined when parentState is undefined (feature
+ * off); otherwise reconstructs from sidechain records with parent's live
+ * replacements filling gaps for fork-inherited mustReapply entries.
+ *
+ * Kept out of AgentTool.tsx — that file is at the feature() DCE complexity
+ * cliff and cannot tolerate even +1 net source line without silently
+ * breaking feature('TRANSCRIPT_CLASSIFIER') eval in tests.
+ */
+export function reconstructForSubagentResume(parentState, resumedMessages, sidechainRecords) {
+    if (!parentState)
+        return undefined;
+    return reconstructContentReplacementState(resumedMessages, sidechainRecords, parentState.replacements);
+}
+/**
+ * Get a human-readable error message from a filesystem error
+ */
+function getFileSystemErrorMessage(error) {
+    // Node.js filesystem errors have a 'code' property
+    // eslint-disable-next-line no-restricted-syntax -- uses .path, not just .code
+    const nodeError = error;
+    if (nodeError.code) {
+        switch (nodeError.code) {
+            case 'ENOENT':
+                return `Directory not found: ${nodeError.path ?? 'unknown path'}`;
+            case 'EACCES':
+                return `Permission denied: ${nodeError.path ?? 'unknown path'}`;
+            case 'ENOSPC':
+                return 'No space left on device';
+            case 'EROFS':
+                return 'Read-only file system';
+            case 'EMFILE':
+                return 'Too many open files';
+            case 'EEXIST':
+                return `File already exists: ${nodeError.path ?? 'unknown path'}`;
+            default:
+                return `${nodeError.code}: ${nodeError.message}`;
+        }
+    }
+    return error.message;
+}