@bubblebrain-ai/bubble 0.0.43 → 0.0.45

package/dist/agent/change-tracker.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Git-ground-truth change tracking for a single agent run.
+ *
+ * Tool-metadata bookkeeping (kind === "write" | "edit" | "patch") misses every
+ * other mutation channel: bash heredocs/sed -i, scripts, subagent worktree
+ * merges. Git sees them all. A baseline snapshot is taken at run start; the
+ * delta at completion time is the run's actual footprint.
+ *
+ * Everything here degrades to null outside a git repo or on any git error —
+ * callers fall back to metadata-based signals.
+ */
+export interface GitChangeBaseline {
+    /** Paths already dirty (or untracked) before the run started. */
+    dirtyAtStart: Set<string>;
+}
+export interface ModifiedExistingTest {
+    path: string;
+    deletedLines: number;
+}
+export interface RunChangeSummary {
+    /** Paths that became dirty during the run (not dirty at baseline). */
+    changedFiles: string[];
+    /**
+     * Pre-existing (tracked) test files that were modified during the run,
+     * with how many lines the working tree deletes from them vs HEAD. New test
+     * files created by the run are NOT listed — creating tests is not suspect.
+     */
+    modifiedExistingTests: ModifiedExistingTest[];
+}
+export declare function isTestFilePath(path: string): boolean;
+export declare function captureGitBaseline(cwd: string): Promise<GitChangeBaseline | null>;
+/**
+ * Diff the current working tree against the run-start baseline.
+ *
+ * Known honest limits: a file already dirty at baseline that the run edited
+ * further is not attributed to the run (indistinguishable without content
+ * snapshots), and deleted-line counts for such files would mix user and agent
+ * edits — so they are excluded entirely.
+ */
+export declare function detectRunChanges(cwd: string, baseline: GitChangeBaseline | null): Promise<RunChangeSummary | null>;

package/dist/agent/change-tracker.js

@@ -0,0 +1,89 @@
+/**
+ * Git-ground-truth change tracking for a single agent run.
+ *
+ * Tool-metadata bookkeeping (kind === "write" | "edit" | "patch") misses every
+ * other mutation channel: bash heredocs/sed -i, scripts, subagent worktree
+ * merges. Git sees them all. A baseline snapshot is taken at run start; the
+ * delta at completion time is the run's actual footprint.
+ *
+ * Everything here degrades to null outside a git repo or on any git error —
+ * callers fall back to metadata-based signals.
+ */
+import { execFile } from "node:child_process";
+const GIT_TIMEOUT_MS = 3_000;
+const TEST_PATH_PATTERN = /(^|\/)(tests?|__tests__|spec)(\/|$)|(\.|_|-)(test|tests|spec)\.[^/]+$|(^|\/)test_[^/]+$/i;
+export function isTestFilePath(path) {
+    return TEST_PATH_PATTERN.test(path);
+}
+function git(cwd, args) {
+    return new Promise((resolve) => {
+        execFile("git", args, { cwd, timeout: GIT_TIMEOUT_MS, maxBuffer: 8 * 1024 * 1024 }, (error, stdout) => {
+            resolve(error ? null : stdout);
+        });
+    });
+}
+/** `git status --porcelain -z` → set of paths with any dirty/untracked state. */
+async function dirtyPaths(cwd) {
+    const out = await git(cwd, ["status", "--porcelain", "-uall", "-z"]);
+    if (out === null)
+        return null;
+    const paths = new Set();
+    for (const entry of out.split("\0")) {
+        if (entry.length < 4)
+            continue;
+        // "XY path" (rename entries "XY new\0old" — the extra segment lacks the
+        // status prefix and is shorter than 4 chars only when degenerate; treat
+        // every segment with the status shape as an entry).
+        const path = entry.slice(3);
+        if (path)
+            paths.add(path);
+    }
+    return paths;
+}
+export async function captureGitBaseline(cwd) {
+    const dirty = await dirtyPaths(cwd);
+    if (dirty === null)
+        return null;
+    return { dirtyAtStart: dirty };
+}
+/**
+ * Diff the current working tree against the run-start baseline.
+ *
+ * Known honest limits: a file already dirty at baseline that the run edited
+ * further is not attributed to the run (indistinguishable without content
+ * snapshots), and deleted-line counts for such files would mix user and agent
+ * edits — so they are excluded entirely.
+ */
+export async function detectRunChanges(cwd, baseline) {
+    if (!baseline)
+        return null;
+    const dirtyNow = await dirtyPaths(cwd);
+    if (dirtyNow === null)
+        return null;
+    const changedFiles = [...dirtyNow].filter((path) => !baseline.dirtyAtStart.has(path)).sort();
+    if (changedFiles.length === 0) {
+        return { changedFiles, modifiedExistingTests: [] };
+    }
+    // Untracked paths are new files; only tracked files count as "existing".
+    const untrackedOut = await git(cwd, ["ls-files", "--others", "--exclude-standard", "-z"]);
+    const untracked = new Set((untrackedOut ?? "").split("\0").filter(Boolean));
+    const modifiedExistingTests = [];
+    const candidates = changedFiles.filter((path) => isTestFilePath(path) && !untracked.has(path));
+    if (candidates.length > 0) {
+        const numstat = await git(cwd, ["diff", "HEAD", "--numstat", "-z", "--", ...candidates]);
+        if (numstat !== null) {
+            // -z numstat entries: "added\tdeleted\tpath\0" (renames add a segment).
+            for (const entry of numstat.split("\0")) {
+                const parts = entry.split("\t");
+                if (parts.length < 3)
+                    continue;
+                const deleted = Number(parts[1]);
+                const path = parts[2];
+                if (!path || Number.isNaN(deleted))
+                    continue;
+                modifiedExistingTests.push({ path, deletedLines: deleted });
+            }
+        }
+    }
+    return { changedFiles, modifiedExistingTests };
+}

package/dist/agent/profiles.js

@@ -155,7 +155,7 @@ export function builtinAgentProfiles() {
                 "You are an implementer subagent working in your own isolated git worktree — the parent tree is never touched.",
                 "Your worktree forks from the last commit; changes the parent made after that commit are NOT present unless included in your briefing.",
                 "Make the smallest coherent edits that complete your assigned group. Stay strictly inside the file set you were given; if a needed change falls outside it, report that instead of editing.",
-                "Verify your changes narrowly (targeted tests or typecheck) when possible, and end with a concise summary of files changed and verification results — the parent reviews and applies your worktree.",
+                "Verify your changes when possible — run the affected module's existing tests, not only the cases you added — and end with a concise summary of files changed and verification results; the parent reviews and applies your worktree.",
             ].join("\n"),
         },
     ];

package/dist/agent.js

@@ -13,7 +13,7 @@ import { buildContextUsageSnapshot } from "./context/usage.js";
 import { isContextOverflowError } from "./context/overflow.js";
 import { computeRetryDelayMs, isProviderStreamInterruption, MAX_STREAM_INTERRUPTION_RETRIES, sleepBeforeRetry, } from "./network/retry.js";
 import { projectMessages } from "./context/projector.js";
-import { aggressivePruneMessages, markStableCurrentToolResultsForCache } from "./context/prune.js";
+import { aggressivePruneMessages, markStableCurrentToolResultsForCache, markToolResultCacheStable } from "./context/prune.js";
 import { truncateToolOutputForModel } from "./context/tool-output-truncate.js";
 import { buildDeferredToolsReminder, buildToolFreezeReminder, reminderForMode } from "./prompt/reminders.js";
 import { HookBus } from "./orchestrator/hooks.js";
@@ -573,6 +573,10 @@ export class Agent {
                 // the redirected one.
                 hookState.exploredFiles?.clear();
                 hookState.largeTaskCheckpointDone = false;
+                // A steer is a new ask: the completion gate must be able to fire
+                // again for the follow-up's closing pass, or appended requirements
+                // never get a self-check (codeChanged stays — prior edits are real).
+                hookState.completionGateFired = false;
                 if (typeof input.content === "string" && input.content.trim()) {
                     hookState.taskType = classifyTask(input.content);
                 }
@@ -1308,13 +1312,17 @@ export class Agent {
                                 limit: truncatedOutput.limit,
                             },
                         }, traceContext);
-                        this.appendMessage({
+                        const toolMessage = {
                             role: "tool",
                             toolCallId: tc.id,
                             content: truncatedOutput.content,
                             metadata: result.metadata,
                             isError: result.isError,
-                        });
+                        };
+                        // Stamp before appending: appendMessage persists to the session log
+                        // synchronously, so a mark added on a later turn never reaches disk.
+                        markToolResultCacheStable(tc.name, toolMessage);
+                        this.appendMessage(toolMessage);
                         this.compactResidentHistory();
                         flushGovernorReminders();
                         this.onToolResult?.(tc.name, result);

package/dist/context/prune.d.ts

@@ -1,10 +1,26 @@
-import type { Message } from "../types.js";
+import type { Message, ToolMessage } from "../types.js";
 export declare function pruneMessages<T extends Message>(messages: T[]): T[];
+/**
+ * Stamp a tool result as "projected in full" at the moment it is appended.
+ *
+ * markStableCurrentToolResultsForCache does the same thing one turn later, which
+ * is too late for the session log: the message is serialized to disk when it is
+ * appended, so a mark added afterwards never reaches the file and a resumed
+ * session re-prunes history the model had already been shown in full.
+ */
+export declare function markToolResultCacheStable(toolName: string, message: ToolMessage): void;
 export declare function markStableCurrentToolResultsForCache(messages: Message[]): void;
 /**
  * Aggressive variant of pruneMessages: drops the content of every prunable
  * tool output except the latest unresolved tool turn that the model still
  * needs to reason over. Used as a last-resort microcompact pass when a
  * standard prune hasn't reclaimed enough budget.
+ *
+ * Deliberately ignores `cacheStableProjection`, unlike pruneMessages. Honouring
+ * it here would make this a no-op — every result that has been sent once is
+ * marked — which is fine for the prefix cache and fatal for the two callers that
+ * depend on it: context-overflow (HTTP 400) recovery and the hard resident-memory
+ * limit. Losing the cache is the correct trade when the alternative is a run that
+ * cannot recover.
  */
 export declare function aggressivePruneMessages<T extends Message>(messages: T[]): T[];

package/dist/context/prune.js

@@ -54,6 +54,22 @@ export function pruneMessages(messages) {
         };
     });
 }
+/**
+ * Stamp a tool result as "projected in full" at the moment it is appended.
+ *
+ * markStableCurrentToolResultsForCache does the same thing one turn later, which
+ * is too late for the session log: the message is serialized to disk when it is
+ * appended, so a mark added afterwards never reaches the file and a resumed
+ * session re-prunes history the model had already been shown in full.
+ */
+export function markToolResultCacheStable(toolName, message) {
+    if (!shouldPruneToolResult(toolName, message.content))
+        return;
+    message.metadata = {
+        ...message.metadata,
+        [CACHE_STABLE_PROJECTION_KEY]: CACHE_STABLE_FULL_PROJECTION,
+    };
+}
 export function markStableCurrentToolResultsForCache(messages) {
     const protectedToolCallIds = collectProtectedToolCallIds(messages);
     if (protectedToolCallIds.size === 0)
@@ -101,6 +117,13 @@ function isCacheStableFullToolResult(message) {
  * tool output except the latest unresolved tool turn that the model still
  * needs to reason over. Used as a last-resort microcompact pass when a
  * standard prune hasn't reclaimed enough budget.
+ *
+ * Deliberately ignores `cacheStableProjection`, unlike pruneMessages. Honouring
+ * it here would make this a no-op — every result that has been sent once is
+ * marked — which is fine for the prefix cache and fatal for the two callers that
+ * depend on it: context-overflow (HTTP 400) recovery and the hard resident-memory
+ * limit. Losing the cache is the correct trade when the alternative is a run that
+ * cannot recover.
  */
 export function aggressivePruneMessages(messages) {
     const toolNameByCallId = new Map();
@@ -128,7 +151,15 @@ export function aggressivePruneMessages(messages) {
 function collectProtectedToolCallIds(messages) {
     for (let index = messages.length - 1; index >= 0; index--) {
         const message = messages[index];
-        if (message.role === "tool" || message.role === "system" || message.role === "meta") {
+        // A trailing user message is steered input (or a resumed session's new
+        // instruction), not the end of the tool batch. Stopping on it left the
+        // just-finished batch unmarked forever, so it stayed a live prune candidate
+        // and later batches rewrote its content mid-history — which both loses tool
+        // output the model may still need and invalidates the provider prefix cache.
+        if (message.role === "tool"
+            || message.role === "system"
+            || message.role === "meta"
+            || message.role === "user") {
             continue;
         }
         if (message.role === "assistant" && message.toolCalls && message.toolCalls.length > 0) {

package/dist/main.js

@@ -575,6 +575,26 @@ async function main() {
             // mode is byte-for-byte the previous behavior.
             const jsonOutput = args.outputFormat === "json";
             const collector = new PrintRunCollector();
+            // Harness-side change footprint (git ground truth) — printed by the
+            // harness so the run cannot omit or misstate what it touched.
+            const changeBaseline = jsonOutput
+                ? await (await import("./agent/change-tracker.js")).captureGitBaseline(args.cwd)
+                : null;
+            const collectChanges = async () => {
+                if (!changeBaseline)
+                    return undefined;
+                const { detectRunChanges } = await import("./agent/change-tracker.js");
+                const detected = await detectRunChanges(args.cwd, changeBaseline).catch(() => null);
+                if (!detected)
+                    return undefined;
+                return {
+                    changed_files: detected.changedFiles.length,
+                    modified_existing_tests: detected.modifiedExistingTests.map((t) => ({
+                        path: t.path,
+                        deleted_lines: t.deletedLines,
+                    })),
+                };
+            };
             const printSessionId = sessionManager
                 ? basename(sessionManager.getSessionFile())
                 : undefined;
@@ -617,6 +637,7 @@ async function main() {
                         summary: collector.summary(),
                         sessionId: printSessionId,
                         compaction: agent.getCompactionStats(),
+                        changes: await collectChanges(),
                     }) + "\n");
                 }
                 else {
@@ -633,6 +654,7 @@ async function main() {
                     summary: collector.summary(),
                     sessionId: printSessionId,
                     compaction: agent.getCompactionStats(),
+                    changes: await collectChanges(),
                 }) + "\n");
                 process.exitCode = 1;
             }

package/dist/model-pricing.d.ts

@@ -6,6 +6,13 @@ export interface ModelPricing {
     currency: PricingCurrency;
     inputCacheHitPerMillion: number;
     inputCacheMissPerMillion: number;
+    /**
+     * Rate for tokens written INTO the cache, when the provider charges a premium
+     * for it (Anthropic: 1.25x base input for the 5-minute TTL). Optional —
+     * without it, cache writes are billed at the plain miss rate, which is what
+     * every provider modelled here did before Anthropic caching was enabled.
+     */
+    inputCacheWritePerMillion?: number;
     outputPerMillion: number;
     effectiveUntil?: string;
     original?: {

package/dist/model-pricing.js

@@ -1,12 +1,56 @@
 export const MODEL_PRICING = [
+    // Anthropic cache multipliers off base input: read 0.1x, 5-minute write 1.25x.
     {
         providerId: "anthropic",
         modelId: "claude-fable-5",
         currency: "USD",
-        inputCacheHitPerMillion: 10,
+        inputCacheHitPerMillion: 1,
         inputCacheMissPerMillion: 10,
+        inputCacheWritePerMillion: 12.5,
         outputPerMillion: 50,
     },
+    {
+        providerId: "anthropic",
+        modelId: "claude-opus-4-8",
+        currency: "USD",
+        inputCacheHitPerMillion: 0.5,
+        inputCacheMissPerMillion: 5,
+        inputCacheWritePerMillion: 6.25,
+        outputPerMillion: 25,
+    },
+    {
+        providerId: "anthropic",
+        modelId: "claude-sonnet-5",
+        currency: "USD",
+        inputCacheHitPerMillion: 0.2,
+        inputCacheMissPerMillion: 2,
+        inputCacheWritePerMillion: 2.5,
+        outputPerMillion: 10,
+        effectiveUntil: "2026-08-31T23:59:00Z",
+        original: {
+            inputCacheHitPerMillion: 0.3,
+            inputCacheMissPerMillion: 3,
+            outputPerMillion: 15,
+        },
+    },
+    {
+        providerId: "anthropic",
+        modelId: "claude-sonnet-4-6",
+        currency: "USD",
+        inputCacheHitPerMillion: 0.3,
+        inputCacheMissPerMillion: 3,
+        inputCacheWritePerMillion: 3.75,
+        outputPerMillion: 15,
+    },
+    {
+        providerId: "anthropic",
+        modelId: "claude-haiku-4-5",
+        currency: "USD",
+        inputCacheHitPerMillion: 0.1,
+        inputCacheMissPerMillion: 1,
+        inputCacheWritePerMillion: 1.25,
+        outputPerMillion: 5,
+    },
     {
         providerId: "deepseek",
         modelId: "deepseek-v4-flash",
@@ -52,8 +96,16 @@ export function calculateUsageCost(providerId, modelId, usage) {
     const miss = hasCacheBreakdown
         ? usage.promptCacheMissTokens ?? Math.max(0, usage.promptTokens - hit)
         : usage.promptTokens;
+    // `miss` already contains the cache-write tokens (see mergeAnthropicUsage),
+    // so writes must be netted out before being re-priced — adding a write term
+    // on top of the untouched miss term would bill them at miss + write.
+    const write = pricing.inputCacheWritePerMillion !== undefined
+        ? Math.min(usage.cacheCreationTokens ?? 0, miss)
+        : 0;
+    const missOnly = miss - write;
     const cost = (hit / 1_000_000) * pricing.inputCacheHitPerMillion
-        + (miss / 1_000_000) * pricing.inputCacheMissPerMillion
+        + (write / 1_000_000) * (pricing.inputCacheWritePerMillion ?? pricing.inputCacheMissPerMillion)
+        + (missOnly / 1_000_000) * pricing.inputCacheMissPerMillion
         + (usage.completionTokens / 1_000_000) * pricing.outputPerMillion;
     return {
         currency: pricing.currency,

package/dist/orchestrator/default-hooks.js

@@ -6,6 +6,7 @@ import { DiscoveryBarrier } from "../agent/discovery-barrier.js";
 import { arbitrateToolCall } from "../agent/tool-arbiter.js";
 import { buildCompletionSelfCheckReminder, buildEditRetryEscalationReminder, buildSmallTaskHint, buildWorkflowPhaseReminder, } from "../prompt/reminders.js";
 import { largeImplementationTaskReminder, orchestrationRequestReminder, reminderForTaskType, userNamedModelReminder } from "../prompt/task-reminders.js";
+import { captureGitBaseline, detectRunChanges } from "../agent/change-tracker.js";
 import { formatCoverageSummary, resolveWorkflowPhase } from "./workflow.js";
 import { resolve as resolvePath } from "node:path";
 import { traceEvent } from "../debug-trace.js";
@@ -14,7 +15,13 @@ import { buildSubagentLifecycleReminder } from "../agent/subagent-lifecycle-remi
 export function createDefaultHooks() {
     return [
         {
-            beforeTurn(ctx) {
+            async beforeTurn(ctx) {
+                // Git ground truth for the completion gate: tool-metadata bookkeeping
+                // misses bash-written files and subagent worktree merges; a dirty-state
+                // baseline at run start makes the run's real footprint observable.
+                if (ctx.state.gitBaseline === undefined) {
+                    ctx.state.gitBaseline = await captureGitBaseline(ctx.cwd);
+                }
                 const taskType = classifyTask(ctx.input);
                 ctx.state.taskType = taskType;
                 ctx.state.governor = new ExecutionGovernor(taskType);
@@ -99,6 +106,7 @@ export function createDefaultHooks() {
         },
         {
             beforeToolCall(ctx) {
+                ctx.state.toolUsed = true;
                 const arbitration = arbitrateToolCall(ctx.toolCall);
                 const toolCall = { ...arbitration.toolCall, ...(arbitration.note ? { arbiterNote: arbitration.note } : {}) };
                 ctx.replaceToolCall(toolCall);
@@ -220,7 +228,7 @@ export function createDefaultHooks() {
                 }
                 // Verification reminders intentionally removed. See afterToolCall.
             },
-            afterTurn(ctx) {
+            async afterTurn(ctx) {
                 // Verification force-continuation removed. The model decides whether
                 // verification is meaningful for the task, per the system prompt.
                 //
@@ -232,21 +240,37 @@ export function createDefaultHooks() {
                 // "prove it" spiral that killed the old design cannot start.
                 if (ctx.state.completionGateFired)
                     return;
-                if (!ctx.state.codeChanged)
-                    return;
                 // Tools are frozen: the model could not act on anything the check
                 // surfaces, so another turn is pure token burn.
                 if (ctx.state.forceTextOnlyReason)
                     return;
                 // Subagents hand off to a parent that does its own closing pass, and
                 // worktree profiles explicitly forbid the very actions a completion
-                // check would suggest.
+                // check would suggest. The parent's gate still covers their merged
+                // changes via the git baseline below.
                 if (ctx.agent.role === "subagent")
                     return;
+                // Change detection: tool metadata first (cheap), then git ground
+                // truth — which also catches bash-written files and subagent
+                // worktree merges. Gate only runs git when the run actually used
+                // tools, so external repo churn cannot hijack a pure Q&A turn.
+                let changes = null;
+                if (ctx.state.toolUsed && ctx.state.gitBaseline) {
+                    changes = await detectRunChanges(ctx.cwd, ctx.state.gitBaseline);
+                }
+                const changedSomething = !!ctx.state.codeChanged || (changes !== null && changes.changedFiles.length > 0);
+                if (!changedSomething)
+                    return;
                 ctx.state.completionGateFired = true;
                 ctx.state.forceContinuationReason = "completion_self_check";
-                ctx.queueReminder(buildCompletionSelfCheckReminder());
-                traceEvent("completion_gate_fired", { turnCount: ctx.state.turnCount });
+                ctx.queueReminder(buildCompletionSelfCheckReminder({
+                    modifiedExistingTests: changes?.modifiedExistingTests,
+                }));
+                traceEvent("completion_gate_fired", {
+                    turnCount: ctx.state.turnCount,
+                    changedFiles: changes?.changedFiles.length,
+                    modifiedExistingTests: changes?.modifiedExistingTests.length,
+                });
             },
         },
     ];

package/dist/orchestrator/hooks.d.ts

@@ -1,5 +1,6 @@
 import type { Agent } from "../agent.js";
 import type { ContentPart, ParsedToolCall, ToolRegistryEntry, ToolResult } from "../types.js";
+import type { GitChangeBaseline } from "../agent/change-tracker.js";
 import type { TaskType } from "../agent/task-classifier.js";
 import type { ExecutionGovernor } from "../agent/execution-governor.js";
 import type { EvidenceTracker } from "../agent/evidence-tracker.js";
@@ -18,6 +19,10 @@ export interface TurnHookState {
     codeChanged?: boolean;
     /** Completion self-check gate already fired this run (fires at most once). */
     completionGateFired?: boolean;
+    /** Git dirty-state snapshot at run start (null = not a git repo / git failed). */
+    gitBaseline?: GitChangeBaseline | null;
+    /** Any tool executed this run — guards git-change attribution for pure Q&A turns. */
+    toolUsed?: boolean;
     smallTaskHintSent?: boolean;
     recentEditFailures?: string[];
     editNoMatchReminderPaths?: string[];

package/dist/print-output.d.ts

@@ -10,9 +10,23 @@
 import type { AgentEvent } from "./types.js";
 export type PrintOutputFormat = "plain" | "json";
 export declare function parseOutputFormat(raw: string | undefined): PrintOutputFormat | undefined;
+/**
+ * Anthropic's usage decomposition, which the field names already claimed to
+ * follow: the four token buckets are DISJOINT and sum to `total_tokens`.
+ *
+ *   input_tokens + cache_read_input_tokens + cache_creation_input_tokens
+ *     + output_tokens === total_tokens
+ *
+ * `input_tokens` is therefore the uncached remainder only — it does NOT include
+ * cache reads. It used to carry the whole prompt total, which was harmless while
+ * cache reads were a flat few thousand tokens per turn, but message-level prompt
+ * caching makes reads 70-90% of the prompt, and a harness that priced
+ * `input_tokens` at the full input rate would then overstate cost ~2x.
+ */
 export interface PrintUsageSummary {
     input_tokens: number;
     cache_read_input_tokens: number;
+    cache_creation_input_tokens: number;
     output_tokens: number;
     reasoning_tokens: number;
     total_tokens: number;
@@ -42,6 +56,18 @@ export declare class PrintRunCollector {
     private addUsage;
     summary(): PrintRunSummary;
 }
+/**
+ * Harness-observed change footprint of the run (git ground truth). Printed
+ * by the harness, not the model — a run cannot omit or misstate what it
+ * touched ("no breaking changes" next to deleted test assertions).
+ */
+export interface PrintChangeSummary {
+    changed_files: number;
+    modified_existing_tests: Array<{
+        path: string;
+        deleted_lines: number;
+    }>;
+}
 /**
  * Per-path counts of context compactions during the run. Lets benchmark
  * harnesses correlate outcomes with "did the model ever lose sight of the
@@ -61,10 +87,12 @@ export declare function formatPrintJson(input: {
     sessionId?: string;
     stopReason?: "end_turn" | "error" | "cancelled";
     compaction?: PrintCompactionStats;
+    changes?: PrintChangeSummary;
 }): string;
 export declare function formatPrintJsonError(input: {
     message: string;
     summary?: PrintRunSummary;
     sessionId?: string;
     compaction?: PrintCompactionStats;
+    changes?: PrintChangeSummary;
 }): string;

package/dist/print-output.js

@@ -23,6 +23,7 @@ export class PrintRunCollector {
     usage = {
         input_tokens: 0,
         cache_read_input_tokens: 0,
+        cache_creation_input_tokens: 0,
         output_tokens: 0,
         reasoning_tokens: 0,
         total_tokens: 0,
@@ -57,8 +58,17 @@ export class PrintRunCollector {
     }
     addUsage(usage) {
         this.usageReported = true;
-        this.usage.input_tokens += usage.promptTokens ?? 0;
-        this.usage.cache_read_input_tokens += usage.promptCacheHitTokens ?? 0;
+        const prompt = usage.promptTokens ?? 0;
+        const cacheRead = usage.promptCacheHitTokens ?? 0;
+        // promptCacheMissTokens already includes creation, so creation has to be
+        // netted out of the uncached remainder rather than added alongside it.
+        const cacheCreation = usage.cacheCreationTokens ?? 0;
+        const uncached = usage.promptCacheMissTokens !== undefined
+            ? Math.max(0, usage.promptCacheMissTokens - cacheCreation)
+            : Math.max(0, prompt - cacheRead - cacheCreation);
+        this.usage.input_tokens += uncached;
+        this.usage.cache_read_input_tokens += cacheRead;
+        this.usage.cache_creation_input_tokens += cacheCreation;
         this.usage.output_tokens += usage.completionTokens ?? 0;
         this.usage.reasoning_tokens += usage.reasoningTokens ?? 0;
         this.usage.total_tokens += usage.totalTokens
@@ -84,6 +94,7 @@ export function formatPrintJson(input) {
         usage: input.summary.usage,
         usage_reported: input.summary.usage_reported,
         ...(input.compaction ? { compaction: input.compaction } : {}),
+        ...(input.changes ? { changes: input.changes } : {}),
     });
 }
 export function formatPrintJsonError(input) {
@@ -101,5 +112,6 @@ export function formatPrintJsonError(input) {
             }
             : {}),
         ...(input.compaction ? { compaction: input.compaction } : {}),
+        ...(input.changes ? { changes: input.changes } : {}),
     });
 }

package/dist/prompt/reminders.d.ts

@@ -23,7 +23,14 @@ export declare function buildInvestigationReminder(): string;
 export declare function buildLoopWarningReminder(reason: string): string;
 export declare function buildSearchFreezeReminder(reason: string): string;
 export declare function buildExplorationFreezeReminder(reason: string): string;
-export declare function buildCompletionSelfCheckReminder(): string;
+export interface CompletionSelfCheckOptions {
+    /** Pre-existing test files this run modified, with deleted-line counts. */
+    modifiedExistingTests?: Array<{
+        path: string;
+        deletedLines: number;
+    }>;
+}
+export declare function buildCompletionSelfCheckReminder(options?: CompletionSelfCheckOptions): string;
 export declare function buildToolFreezeReminder(reason: string): string;
 export declare function buildWorkflowPhaseReminder(input: {
     phase: "investigate" | "correlate" | "conclude";

package/dist/prompt/reminders.js

@@ -116,15 +116,30 @@ You have enough context to act. Do not continue reading, searching, or delegatin
 Choose one of:
 1. Use edit/write to make the requested change.
 2. If no safe change can be made from the gathered context, explain the concrete blocker.
-3. If files were already changed, run the narrowest meaningful verification or finish with the result.
+3. If files were already changed, verify the change and run the affected module's existing tests, or finish with the result.
 `);
 }
-export function buildCompletionSelfCheckReminder() {
-    return wrapInSystemReminder(`
-You appear to be finishing. Before giving your final answer, re-read the user's original request in this conversation and check whether any explicit requirement in it remains unfulfilled — including requirements about how the work should be delivered or reported, not only whether the implementation works.
+export function buildCompletionSelfCheckReminder(options = {}) {
+    const sections = [];
+    const modifiedTests = options.modifiedExistingTests ?? [];
+    if (modifiedTests.length > 0) {
+        // Disclosure, not accusation: legitimate test updates (requirement
+        // changes, fixing a broken test, refactors) are normal engineering — the
+        // rule is that they must be declared, never silent. Confrontational
+        // wording risks a model rolling back a user-requested test update.
+        const listed = modifiedTests
+            .slice(0, 8)
+            .map((t) => `- ${t.path}${t.deletedLines > 0 ? ` (${t.deletedLines} line${t.deletedLines === 1 ? "" : "s"} removed)` : ""}`)
+            .join("\n");
+        sections.push(`This run modified pre-existing test files:
+${listed}${modifiedTests.length > 8 ? `\n- …and ${modifiedTests.length - 8} more` : ""}
+
+If a change you made caused an existing test to fail and you edited the test so the suite passes, restore the original behavior instead — weakening a test to make it pass is never acceptable. If the test changes are intentional (the request requires new expected behavior, or the test itself was wrong), keep them and state each modified test and the reason in your final summary.`);
+    }
+    sections.push(`You appear to be finishing. Before giving your final answer, re-read the user's original request in this conversation and check whether any explicit requirement in it remains unfulfilled — including requirements about how the work should be delivered or reported, not only whether the implementation works.
 
-If something is missing, complete it now. If everything is done, give your final answer directly — do not repeat this check or re-verify work you have already verified.
-`);
+If something is missing, complete it now. If everything is done, give your final answer directly — do not repeat this check or re-verify work you have already verified.`);
+    return wrapInSystemReminder(`\n${sections.join("\n\n")}\n`);
 }
 export function buildToolFreezeReminder(reason) {
     return wrapInSystemReminder(`

package/dist/prompt/task-reminders.js

@@ -24,7 +24,7 @@ Implementation workflow:
 - Do not stop at a proposal when the user asked for a change.
 - Inspect the relevant files first, then make the smallest coherent edit.
 - Keep unrelated files and behavior out of scope.
-- Run a narrow verification command or explain why it cannot be run.
+- Verify the change, then run the existing tests of the affected module — not only the cases you added — or explain why they cannot be run.
 `);
         case "code_review":
             return wrapInSystemReminder(`

package/dist/provider-anthropic.d.ts

@@ -36,6 +36,7 @@ interface AnthropicSystemBlock {
 type AnthropicContentBlock = {
     type: "text";
     text: string;
+    cache_control?: AnthropicCacheControl;
 } | {
     type: "image";
     source: {
@@ -46,6 +47,7 @@ type AnthropicContentBlock = {
         media_type: string;
         data: string;
     };
+    cache_control?: AnthropicCacheControl;
 } | {
     type: "thinking";
     thinking: string;
@@ -58,11 +60,13 @@ type AnthropicContentBlock = {
     id: string;
     name: string;
     input: Record<string, unknown>;
+    cache_control?: AnthropicCacheControl;
 } | {
     type: "tool_result";
     tool_use_id: string;
     content: string;
     is_error?: boolean;
+    cache_control?: AnthropicCacheControl;
 };
 interface AnthropicMessage {
     role: "user" | "assistant";
@@ -83,6 +87,28 @@ export declare function buildAnthropicRequest(options: AnthropicProviderOptions,
     thinkingLevel?: ThinkingLevel;
     stream?: boolean;
 }): AnthropicRequest;
+/**
+ * Roll prompt-cache breakpoints along the conversation so each turn's context is
+ * read back on the next turn instead of being re-billed as fresh input.
+ *
+ * Two breakpoints, and both are load-bearing:
+ *
+ * - the **tail** (last block of the last message) writes the entry that the next
+ *   request reads;
+ * - the **anchor** reads it. It goes on the message just before the final
+ *   assistant message — which is exactly where the previous request ended, since
+ *   consecutive agent-loop requests differ by one `[assistant, tool results]`
+ *   step. Landing on the written position directly is what makes this correct
+ *   for any turn size: Anthropic only looks back 20 content blocks from a
+ *   breakpoint to find a prior write, and a turn with many parallel tool calls
+ *   easily exceeds that (1 + 2N blocks for N calls). Measured on Opus 4.8 with
+ *   30 parallel calls: tail-only and a fixed-distance anchor both collapse to an
+ *   8.6% hit rate, while this anchor holds 77%.
+ *
+ * Mutates `messages` (built fresh per request by toAnthropicMessages) and
+ * returns how many breakpoints it used, never more than `budget`.
+ */
+export declare function placeMessageCacheBreakpoints(messages: AnthropicMessage[], budget: number): number;
 export declare function resolveAnthropicMaxTokens(options: AnthropicProviderOptions, model: string): number;
 export declare function supportsAnthropicPromptCache(options: AnthropicProviderOptions, model: string): boolean;
 export declare function toAnthropicMessages(messages: ProviderMessage[], echoThinking?: boolean): {

package/dist/provider-anthropic.js

@@ -12,6 +12,8 @@ const ANTHROPIC_LONG_OUTPUT_MAX_TOKENS = 64000;
 const MINIMAX_M3_MAX_TOKENS = 128000;
 const MINIMAX_M2_MAX_TOKENS = 64000;
 const ANTHROPIC_PROMPT_CACHE_CONTROL = { type: "ephemeral" };
+/** Hard API limit: a 5th cache_control breakpoint is a 400, not a warning. */
+const ANTHROPIC_MAX_CACHE_BREAKPOINTS = 4;
 const MINIMAX_PROMPT_CACHE_MODELS = new Set([
     "minimax-m2.7",
     "minimax-m2.7-highspeed",
@@ -89,11 +91,30 @@ export function buildAnthropicRequest(options, messages, chatOptions) {
         description: tool.description,
         input_schema: tool.parameters,
     }));
+    // Anthropic caps a request at 4 cache_control breakpoints and rejects the
+    // fifth outright, so the static ones are counted and the message region only
+    // ever gets what is left.
+    let staticBreakpoints = 0;
     if (enablePromptCache && tools && tools.length > 0) {
         tools[tools.length - 1] = {
             ...tools[tools.length - 1],
             cache_control: ANTHROPIC_PROMPT_CACHE_CONTROL,
         };
+        staticBreakpoints += 1;
+    }
+    if (enablePromptCache && system) {
+        staticBreakpoints += 1;
+    }
+    // Message-region breakpoints go to the official endpoint only. `baseURL` is
+    // user-editable persisted config, so a corporate gateway can keep
+    // providerId "anthropic" while pointing elsewhere — the URL check is the only
+    // trustworthy signal. Streaming only: complete() has no next turn to read the
+    // entry back.
+    if (enablePromptCache
+        && chatOptions.stream === true
+        && isOfficialAnthropicBaseUrl(options.baseURL)
+        && !messageCacheKillSwitchEnabled()) {
+        placeMessageCacheBreakpoints(anthropicMessages, ANTHROPIC_MAX_CACHE_BREAKPOINTS - staticBreakpoints);
     }
     const effectiveThinkingLevel = normalizeThinkingLevel(chatOptions.thinkingLevel ?? options.thinkingLevel ?? "off", getAvailableThinkingLevels(options.providerId || "", chatOptions.model));
     const body = {
@@ -126,6 +147,95 @@ export function buildAnthropicRequest(options, messages, chatOptions) {
     }
     return body;
 }
+/**
+ * Attach `cache_control` to the last cacheable block of `message`.
+ *
+ * Returns false when the message has nothing markable (empty block array, or a
+ * body made only of thinking blocks, where `cache_control` is not permitted).
+ */
+function markLastCacheableBlock(message) {
+    if (typeof message.content === "string") {
+        if (!message.content)
+            return false;
+        // A breakpoint needs a block to sit on. Wrapping is safe: the API keys the
+        // cache on canonicalised content, so the same message reverting to a bare
+        // string on a later turn still matches this entry.
+        message.content = [{
+                type: "text",
+                text: message.content,
+                cache_control: ANTHROPIC_PROMPT_CACHE_CONTROL,
+            }];
+        return true;
+    }
+    const blocks = message.content;
+    for (let index = blocks.length - 1; index >= 0; index--) {
+        const block = blocks[index];
+        if (block.type === "thinking" || block.type === "redacted_thinking")
+            continue;
+        blocks[index] = { ...block, cache_control: ANTHROPIC_PROMPT_CACHE_CONTROL };
+        return true;
+    }
+    return false;
+}
+/**
+ * Roll prompt-cache breakpoints along the conversation so each turn's context is
+ * read back on the next turn instead of being re-billed as fresh input.
+ *
+ * Two breakpoints, and both are load-bearing:
+ *
+ * - the **tail** (last block of the last message) writes the entry that the next
+ *   request reads;
+ * - the **anchor** reads it. It goes on the message just before the final
+ *   assistant message — which is exactly where the previous request ended, since
+ *   consecutive agent-loop requests differ by one `[assistant, tool results]`
+ *   step. Landing on the written position directly is what makes this correct
+ *   for any turn size: Anthropic only looks back 20 content blocks from a
+ *   breakpoint to find a prior write, and a turn with many parallel tool calls
+ *   easily exceeds that (1 + 2N blocks for N calls). Measured on Opus 4.8 with
+ *   30 parallel calls: tail-only and a fixed-distance anchor both collapse to an
+ *   8.6% hit rate, while this anchor holds 77%.
+ *
+ * Mutates `messages` (built fresh per request by toAnthropicMessages) and
+ * returns how many breakpoints it used, never more than `budget`.
+ */
+export function placeMessageCacheBreakpoints(messages, budget) {
+    // One-shot prompts (complete(): compaction, titles, memory) are excluded by
+    // the caller's streaming gate, not here — a single-message first turn is a
+    // real agent turn and marking its tail costs nothing, since writes are billed
+    // from the highest hit to the last breakpoint regardless of how many sit in
+    // between.
+    if (budget <= 0 || messages.length === 0)
+        return 0;
+    let used = 0;
+    const tailIndex = messages.length - 1;
+    if (budget - used >= 2) {
+        let lastAssistantIndex = -1;
+        for (let index = tailIndex; index >= 0; index--) {
+            if (messages[index].role === "assistant") {
+                lastAssistantIndex = index;
+                break;
+            }
+        }
+        const anchorIndex = lastAssistantIndex - 1;
+        // An assistant at the anchor position means consecutive assistant messages
+        // merged, so this is not the previous request's boundary and the distance
+        // back is unbounded — skip rather than guess.
+        if (anchorIndex >= 0
+            && anchorIndex < tailIndex
+            && messages[anchorIndex].role !== "assistant"
+            && markLastCacheableBlock(messages[anchorIndex])) {
+            used += 1;
+        }
+    }
+    if (budget - used >= 1 && markLastCacheableBlock(messages[tailIndex])) {
+        used += 1;
+    }
+    return used;
+}
+function messageCacheKillSwitchEnabled() {
+    const raw = process.env.BUBBLE_ANTHROPIC_MESSAGE_CACHE;
+    return raw === "0" || raw === "false";
+}
 export function resolveAnthropicMaxTokens(options, model) {
     // MiniMax needs a large output budget so thinking doesn't starve the answer.
     if (isMiniMaxProvider(options)) {
@@ -650,9 +760,18 @@ function mergeAnthropicUsage(current, raw) {
     let promptCacheMissTokens = current?.promptCacheMissTokens;
     let cacheCreationTokens = current?.cacheCreationTokens;
     if (hasPromptUsage) {
-        const inputTokens = rawInput ?? promptCacheMissTokens ?? promptTokens;
+        // Every field carries forward: a message_delta may report one of the three
+        // without the others, and defaulting a missing one to 0 would deflate
+        // promptTokens — which is the compaction anchor (agent lastInputTokens),
+        // so an undercount makes the agent compact later than it should.
+        // promptCacheMissTokens already includes cache creation, so the prior
+        // uncached remainder has to net it back out before being reused.
+        const priorUncachedInput = promptCacheMissTokens !== undefined
+            ? Math.max(0, promptCacheMissTokens - (cacheCreationTokens ?? 0))
+            : promptTokens;
+        const inputTokens = rawInput ?? priorUncachedInput;
         const cacheRead = rawCacheRead ?? promptCacheHitTokens ?? 0;
-        const cacheCreation = rawCacheCreation ?? 0;
+        const cacheCreation = rawCacheCreation ?? cacheCreationTokens ?? 0;
         promptTokens = inputTokens + cacheRead + cacheCreation;
         promptCacheHitTokens = cacheRead;
         promptCacheMissTokens = inputTokens + cacheCreation;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bubblebrain-ai/bubble",
-  "version": "0.0.43",
+  "version": "0.0.45",
   "description": "A terminal coding agent",
   "type": "module",
   "engines": {