codeep 2.0.1 → 2.0.2

package/dist/acp/commands.js

@@ -600,6 +600,62 @@ Anything else the agent should know — edge cases, gotchas, things to double-ch
             }
         }
         // ─── Export ────────────────────────────────────────────────────────────────
+        // ─── Plan mode (2.0.2) ────────────────────────────────────────────────────
+        case 'plan': {
+            // Identical contract to TUI /plan: generate a pre-execution plan,
+            // surface it, hold as pending so /go can execute it without re-planning.
+            if (!args.length) {
+                const { getPendingPlan } = await import('../utils/planMode.js');
+                const cur = getPendingPlan();
+                return {
+                    handled: true,
+                    response: cur
+                        ? `**Pending plan for:** _${cur.task}_\n\n${cur.plan}\n\n---\nRun \`/go\` to execute, or \`/plan <revised task>\` to revise.`
+                        : 'Usage: `/plan <task>` — generates a plan you can review, then `/go` to execute.',
+                };
+            }
+            const task = args.join(' ');
+            onChunk(`_Generating plan for: ${task.slice(0, 80)}${task.length > 80 ? '…' : ''}_\n\n`);
+            try {
+                const { generatePlan } = await import('../utils/planMode.js');
+                const plan = await generatePlan(task);
+                return {
+                    handled: true,
+                    response: `${plan}\n\n---\nRun \`/go\` to execute this plan, or \`/plan <revised task>\` to refine it.`,
+                    streaming: true,
+                };
+            }
+            catch (err) {
+                return { handled: true, response: `Plan generation failed: ${err.message}`, streaming: true };
+            }
+        }
+        case 'go': {
+            const { getPendingPlan, composeExecutionPrompt, clearPendingPlan } = await import('../utils/planMode.js');
+            const cur = getPendingPlan();
+            if (!cur) {
+                return { handled: true, response: 'No pending plan. Run `/plan <task>` first.' };
+            }
+            const prompt = composeExecutionPrompt(cur);
+            clearPendingPlan();
+            onChunk(`_Executing approved plan…_\n\n`);
+            try {
+                const { buildProjectContext } = await import('./session.js');
+                const ctx = buildProjectContext(session.workspaceRoot);
+                const agentResult = await runAgent(prompt, ctx, {
+                    abortSignal,
+                    onIteration: (_i, msg) => { onChunk(msg + '\n'); },
+                    onThinking: (text) => { onChunk(text); },
+                });
+                return {
+                    handled: true,
+                    response: agentResult.finalResponse || '_(plan executed; no final summary)_',
+                    streaming: true,
+                };
+            }
+            catch (err) {
+                return { handled: true, response: `Plan execution failed: ${err.message}`, streaming: true };
+            }
+        }
         case 'export': {
             if (!session.history.length)
                 return { handled: true, response: 'No messages to export.' };

package/dist/acp/server.js

@@ -52,6 +52,9 @@ const AVAILABLE_COMMANDS = [
     { name: 'mcp', description: 'Manage MCP servers, marketplace, resources, prompts', input: { hint: '[browse | install <id> | add | remove | reload | resources | read <uri> | prompts | prompt <server> <name>]' } },
     { name: 'openrouter', description: 'OpenRouter routing preferences (prefer/ignore/fallbacks/privacy/clear)', input: { hint: '[show | prefer <p,...> | ignore <p,...> | fallbacks on|off | privacy strict|allow | clear]' } },
     { name: 'export', description: 'Export conversation', input: { hint: 'json | md | txt' } },
+    // Plan mode (2.0.2)
+    { name: 'plan', description: 'Generate a numbered plan for a task — review before /go executes', input: { hint: '<task>' } },
+    { name: 'go', description: 'Execute the pending plan from /plan' },
     // Project intelligence
     { name: 'scan', description: 'Scan project structure and generate summary' },
     { name: 'review', description: 'Run code review on project or specific files', input: { hint: '[file…]' } },

package/dist/api/index.js

@@ -593,6 +593,13 @@ async function chatAnthropic(message, history, model, apiKey, onChunk, abortSign
         headers['x-api-key'] = apiKey;
     }
     try {
+        // Anthropic prompt caching: wrap system as an array with a
+        // `cache_control` marker so the static system prompt (typically large
+        // and stable across a session) is cached. Below 1024 input tokens
+        // Anthropic silently skips caching — no error.
+        const cachedSystem = useNativeSystem
+            ? { system: [{ type: 'text', text: systemPrompt, cache_control: { type: 'ephemeral' } }] }
+            : {};
         const response = await fetch(`${baseUrl}/v1/messages`, {
             method: 'POST',
             headers,
@@ -602,7 +609,7 @@ async function chatAnthropic(message, history, model, apiKey, onChunk, abortSign
                 max_tokens: maxTokens,
                 temperature,
                 stream,
-                ...(useNativeSystem ? { system: systemPrompt } : {}),
+                ...cachedSystem,
             }),
             signal: controller.signal,
         });
@@ -649,6 +656,8 @@ async function handleAnthropicStream(body, onChunk) {
     let buffer = '';
     let inputTokens = 0;
     let outputTokens = 0;
+    let cacheCreationTokens = 0;
+    let cacheReadTokens = 0;
     let streamModel = '';
     while (true) {
         const { done, value } = await reader.read();
@@ -669,9 +678,13 @@ async function handleAnthropicStream(body, onChunk) {
                             onChunk(text);
                         }
                     }
-                    // message_start contains input_tokens
+                    // message_start contains input_tokens (and cache create/read
+                    // when prompt caching is in play).
                     if (parsed.type === 'message_start' && parsed.message?.usage) {
-                        inputTokens = parsed.message.usage.input_tokens || 0;
+                        const u = parsed.message.usage;
+                        inputTokens = u.input_tokens || 0;
+                        cacheCreationTokens = u.cache_creation_input_tokens || 0;
+                        cacheReadTokens = u.cache_read_input_tokens || 0;
                         streamModel = parsed.message.model || '';
                     }
                     // message_delta contains output_tokens
@@ -686,8 +699,15 @@ async function handleAnthropicStream(body, onChunk) {
         }
     }
     // Record token usage
-    if (inputTokens > 0 || outputTokens > 0) {
-        recordTokenUsage({ promptTokens: inputTokens, completionTokens: outputTokens, totalTokens: inputTokens + outputTokens }, streamModel || 'unknown', config.get('provider'));
+    if (inputTokens > 0 || outputTokens > 0 || cacheReadTokens > 0 || cacheCreationTokens > 0) {
+        const totalPrompt = inputTokens + cacheCreationTokens + cacheReadTokens;
+        recordTokenUsage({
+            promptTokens: totalPrompt,
+            completionTokens: outputTokens,
+            totalTokens: totalPrompt + outputTokens,
+            cacheCreationTokens: cacheCreationTokens || undefined,
+            cacheReadTokens: cacheReadTokens || undefined,
+        }, streamModel || 'unknown', config.get('provider'));
     }
     // Strip <think> tags from MiniMax responses
     return stripThinkTags(chunks.join(''));

package/dist/renderer/App.js

@@ -91,6 +91,8 @@ const COMMAND_DESCRIPTIONS = {
     'hooks': 'List installed lifecycle hooks (.codeep/hooks/<event>.sh)',
     'mcp': 'Manage MCP servers (browse, install, add, remove, resources, prompts)',
     'openrouter': 'Tune OpenRouter routing (preferred / ignore providers, fallbacks, privacy)',
+    'plan': 'Generate a numbered plan for a task — review before /go executes it',
+    'go': 'Execute the pending plan from /plan',
 };
 import { helpCategories, keyboardShortcuts } from './components/Help.js';
 import { handleSettingsKey, SETTINGS } from './components/Settings.js';
@@ -230,6 +232,8 @@ export class App {
         // Keep in lockstep with COMMAND_DESCRIPTIONS below and helpCategories.
         'compact', 'commands', 'checkpoint', 'checkpoints', 'rewind',
         'hooks', 'mcp', 'openrouter',
+        // 2.0.2 — plan mode.
+        'plan', 'go',
         'c', 't', 'd', 'r', 'f', 'e', 'o', 'b', 'p',
     ];
     constructor(options) {

package/dist/renderer/commands.js

@@ -216,6 +216,65 @@ export async function handleCommand(command, args, ctx) {
             runAgentTask(args.join(' '), true, ctx, () => null, () => { });
             break;
         }
+        case 'plan': {
+            // Plan mode: ask the model for a plan, surface it, hold as pending.
+            // The user runs /go to execute or /plan <revised> to revise. See
+            // src/utils/planMode.ts for the rationale + system prompt.
+            if (!args.length) {
+                const { getPendingPlan } = await import('../utils/planMode.js');
+                const cur = getPendingPlan();
+                if (cur) {
+                    ctx.app.addMessage({
+                        role: 'system',
+                        content: `**Pending plan for:** _${cur.task}_\n\n${cur.plan}\n\n---\nRun \`/go\` to execute, or \`/plan <revised task>\` to revise.`,
+                    });
+                }
+                else {
+                    ctx.app.notify('Usage: /plan <task> — generates a plan you can review, then /go to execute.');
+                }
+                return;
+            }
+            if (ctx.isAgentRunning()) {
+                ctx.app.notify('Agent already running. Use /stop first.');
+                return;
+            }
+            const task = args.join(' ');
+            ctx.app.addMessage({ role: 'user', content: `/plan ${task}` });
+            ctx.app.notify('Generating plan…');
+            try {
+                const { generatePlan } = await import('../utils/planMode.js');
+                const plan = await generatePlan(task);
+                ctx.app.addMessage({
+                    role: 'assistant',
+                    content: `${plan}\n\n---\nRun \`/go\` to execute this plan, or \`/plan <revised task>\` to refine it.`,
+                });
+            }
+            catch (err) {
+                ctx.app.notify(`Plan generation failed: ${err.message}`);
+            }
+            break;
+        }
+        case 'go': {
+            // Execute the pending plan from /plan. The agent loop sees the
+            // task + plan as a single prompt, so MCP tools, hooks, permissions,
+            // and verification all apply unchanged.
+            const { getPendingPlan, composeExecutionPrompt, clearPendingPlan } = await import('../utils/planMode.js');
+            const cur = getPendingPlan();
+            if (!cur) {
+                ctx.app.notify('No pending plan. Run `/plan <task>` first.');
+                return;
+            }
+            if (ctx.isAgentRunning()) {
+                ctx.app.notify('Agent already running. Use /stop first.');
+                return;
+            }
+            const prompt = composeExecutionPrompt(cur);
+            clearPendingPlan();
+            ctx.app.notify(`Executing plan for: ${cur.task.slice(0, 80)}${cur.task.length > 80 ? '…' : ''}`);
+            const { runAgentTask } = await import('./agentExecution.js');
+            runAgentTask(prompt, false, ctx, () => null, () => { });
+            break;
+        }
         case 'stop': {
             if (ctx.isAgentRunning() && ctx.abortController) {
                 ctx.abortController.abort();

package/dist/renderer/components/Help.js

@@ -46,6 +46,8 @@ export const helpCategories = [
         items: [
             { key: '/agent <task>', description: 'Run agent with task' },
             { key: '/agent-dry <task>', description: 'Dry run (no changes)' },
+            { key: '/plan <task>', description: 'Generate a plan first — review before /go executes' },
+            { key: '/go', description: 'Execute the pending plan from /plan' },
             { key: '/stop', description: 'Stop running agent' },
             { key: '/undo', description: 'Undo last agent action' },
             { key: '/undo-all', description: 'Undo all agent actions' },

package/dist/utils/agentChat.js

@@ -301,9 +301,25 @@ additionalTools) {
         }
         else {
             endpoint = `${baseUrl}/v1/messages`;
+            // Anthropic prompt caching. Two cache breakpoints:
+            //   1. `system` (largest stable block — system prompt + skills catalog)
+            //   2. last tool in `tools` (Anthropic caches everything up to and
+            //      including the marker, so this caches the entire tools array)
+            // Cache hits cost 0.1× input. Misses ("cache creation") cost 1.25×.
+            // Net win after the 2nd same-shape request. Below 1024 input tokens
+            // Anthropic silently skips caching — no error path to handle.
+            const anthropicTools = getAnthropicTools(additionalTools);
+            const cachedTools = anthropicTools.length > 0
+                ? [
+                    ...anthropicTools.slice(0, -1),
+                    { ...anthropicTools[anthropicTools.length - 1], cache_control: { type: 'ephemeral' } },
+                ]
+                : anthropicTools;
             body = {
-                model, system: systemPrompt, messages,
-                tools: getAnthropicTools(additionalTools), stream: useStreaming,
+                model,
+                system: [{ type: 'text', text: systemPrompt, cache_control: { type: 'ephemeral' } }],
+                messages,
+                tools: cachedTools, stream: useStreaming,
                 ...tempParam, max_tokens: getEffectiveMaxTokens(providerId, Math.max(config.get('maxTokens'), 16384)),
             };
         }
@@ -435,10 +451,15 @@ export async function agentChatFallback(messages, systemPrompt, onChunk, abortSi
         }
         else {
             endpoint = `${baseUrl}/v1/messages`;
+            // Fallback path injects system+tools as the first user message
+            // (no native tool API). Cache that block — it's large and stable.
             body = {
                 model,
                 messages: [
-                    { role: 'user', content: fallbackPrompt },
+                    {
+                        role: 'user',
+                        content: [{ type: 'text', text: fallbackPrompt, cache_control: { type: 'ephemeral' } }],
+                    },
                     { role: 'assistant', content: 'Understood. I will use the tools as specified.' },
                     ...messages,
                 ],

package/dist/utils/agentStream.js

@@ -169,13 +169,30 @@ export async function handleAnthropicAgentStream(body, onChunk, model, providerI
             const data = line.slice(6);
             try {
                 const parsed = JSON.parse(data);
-                // message_start has input tokens; message_delta has output tokens — merge both
+                // message_start has input tokens (incl. cache create/read fields if
+                // prompt caching is in use); message_delta has output tokens —
+                // merge both so extractAnthropicUsage sees the full picture.
                 if (parsed.type === 'message_start' && parsed.message?.usage) {
-                    usageData = { usage: { input_tokens: parsed.message.usage.input_tokens || 0, output_tokens: 0 } };
+                    const u = parsed.message.usage;
+                    usageData = {
+                        usage: {
+                            input_tokens: u.input_tokens || 0,
+                            output_tokens: 0,
+                            cache_creation_input_tokens: u.cache_creation_input_tokens || 0,
+                            cache_read_input_tokens: u.cache_read_input_tokens || 0,
+                        },
+                    };
                 }
                 else if (parsed.type === 'message_delta' && parsed.usage) {
-                    const inputTokens = usageData?.usage?.input_tokens || 0;
-                    usageData = { usage: { input_tokens: inputTokens, output_tokens: parsed.usage.output_tokens || 0 } };
+                    const prev = usageData?.usage ?? {};
+                    usageData = {
+                        usage: {
+                            input_tokens: prev.input_tokens || 0,
+                            output_tokens: parsed.usage.output_tokens || 0,
+                            cache_creation_input_tokens: prev.cache_creation_input_tokens || 0,
+                            cache_read_input_tokens: prev.cache_read_input_tokens || 0,
+                        },
+                    };
                 }
                 if (parsed.type === 'content_block_start') {
                     const block = parsed.content_block;

package/dist/utils/planMode.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Plan mode — explicit pre-execution preview.
+ *
+ * Flow:
+ *   1. User runs `/plan <task>` — we ask the LLM for a numbered plan
+ *      (no tool calls, no file changes) and surface it to the user.
+ *   2. We hold the (task, plan) pair as the *pending* plan, scoped to
+ *      the current process.
+ *   3. User runs `/go` to execute, or `/plan <revised task>` to refine.
+ *      `/go` hands the original task + approved plan to the regular
+ *      agent loop as a single prompt, so the existing tool execution,
+ *      verification, and permission paths apply unchanged.
+ *
+ * Why this design (MVP):
+ *   - Zero changes to the agent loop, MCP wiring, or ACP server.
+ *   - Plan rendering reuses the chat markdown renderer (no new TUI
+ *     panel to maintain).
+ *   - Edit flow is just "/plan <revised task>" — generates a new plan
+ *     that replaces the pending one; user pays one extra LLM call but
+ *     gets human-readable revision history in the chat above.
+ *   - When we ship a proper plan-mode UI later (TUI panel with
+ *     Accept/Edit/Reject buttons + per-step progress), it can keep
+ *     using this module as the backend.
+ */
+export interface PendingPlan {
+    task: string;
+    plan: string;
+    createdAt: number;
+}
+/**
+ * Ask the model for a plan for the given task. Stores the (task, plan)
+ * pair as the pending plan so a subsequent `/go` can execute it.
+ * Throws on chat failure — caller renders the error.
+ */
+export declare function generatePlan(task: string, onChunk?: (text: string) => void): Promise<string>;
+export declare function getPendingPlan(): PendingPlan | null;
+export declare function clearPendingPlan(): void;
+/**
+ * Compose the prompt the agent loop receives when the user runs `/go`.
+ * The agent treats this as a normal task, so tool calls / verification /
+ * permissions / hooks all flow through the existing paths — we just
+ * front-load the plan as context so the model doesn't re-plan
+ * implicitly.
+ */
+export declare function composeExecutionPrompt(plan: PendingPlan): string;

package/dist/utils/planMode.js

@@ -0,0 +1,94 @@
+/**
+ * Plan mode — explicit pre-execution preview.
+ *
+ * Flow:
+ *   1. User runs `/plan <task>` — we ask the LLM for a numbered plan
+ *      (no tool calls, no file changes) and surface it to the user.
+ *   2. We hold the (task, plan) pair as the *pending* plan, scoped to
+ *      the current process.
+ *   3. User runs `/go` to execute, or `/plan <revised task>` to refine.
+ *      `/go` hands the original task + approved plan to the regular
+ *      agent loop as a single prompt, so the existing tool execution,
+ *      verification, and permission paths apply unchanged.
+ *
+ * Why this design (MVP):
+ *   - Zero changes to the agent loop, MCP wiring, or ACP server.
+ *   - Plan rendering reuses the chat markdown renderer (no new TUI
+ *     panel to maintain).
+ *   - Edit flow is just "/plan <revised task>" — generates a new plan
+ *     that replaces the pending one; user pays one extra LLM call but
+ *     gets human-readable revision history in the chat above.
+ *   - When we ship a proper plan-mode UI later (TUI panel with
+ *     Accept/Edit/Reject buttons + per-step progress), it can keep
+ *     using this module as the backend.
+ */
+import { chat } from '../api/index.js';
+const PLAN_SYSTEM_PROMPT = `You are in PLAN MODE.
+
+The user has given you a task. **Do not execute anything.** Do not call
+tools. Do not modify files. Do not run shell commands. Instead, produce
+a numbered plan of the steps you would take, so the user can review and
+approve before any changes happen.
+
+Format your response as Markdown:
+
+## Plan: <one-line summary of the task>
+
+1. **<short step name>** — what you'd do (e.g. read file, edit lines, run command).
+   _Why:_ rationale (1 sentence).
+   _Expected outcome:_ what the user should see after this step.
+
+2. **<step name>** — …
+
+(continue numbering)
+
+End with these three lines (verbatim labels, fill in values):
+
+**Risk:** <low | medium | high> — <one-sentence reason; e.g. "schema change, requires migration">
+**Files affected:** <comma-separated list of paths you'd touch, or "none">
+**Commands run:** <comma-separated shell commands, or "none">
+
+Rules:
+- Be concrete. Reference real file paths from the project if you know them.
+- Keep steps small enough that each maps to one or two tool calls when
+  later executed.
+- If the task is ambiguous, list the assumption(s) you're making at the
+  top of the plan ("Assumes: ...") so the user can correct before /go.
+- Do NOT produce code — describe what you'd change, not the change
+  itself. Code generation belongs in execution, not planning.
+- If the task is trivial (single-file rename, single-line edit), say so
+  in one sentence and skip the formal plan — don't bloat tiny work.`;
+let pending = null;
+/**
+ * Ask the model for a plan for the given task. Stores the (task, plan)
+ * pair as the pending plan so a subsequent `/go` can execute it.
+ * Throws on chat failure — caller renders the error.
+ */
+export async function generatePlan(task, onChunk) {
+    const history = [
+        { role: 'system', content: PLAN_SYSTEM_PROMPT },
+    ];
+    const plan = await chat(task, history, onChunk);
+    pending = { task, plan, createdAt: Date.now() };
+    return plan;
+}
+export function getPendingPlan() {
+    return pending;
+}
+export function clearPendingPlan() {
+    pending = null;
+}
+/**
+ * Compose the prompt the agent loop receives when the user runs `/go`.
+ * The agent treats this as a normal task, so tool calls / verification /
+ * permissions / hooks all flow through the existing paths — we just
+ * front-load the plan as context so the model doesn't re-plan
+ * implicitly.
+ */
+export function composeExecutionPrompt(plan) {
+    return `${plan.task}
+
+I've reviewed the following plan and approved it. Execute it step by step. If any step turns out to be wrong or impossible mid-execution, stop and report — don't silently improvise.
+
+${plan.plan}`;
+}

package/dist/utils/tokenTracker.d.ts

@@ -5,6 +5,13 @@ export interface TokenUsage {
     promptTokens: number;
     completionTokens: number;
     totalTokens: number;
+    /** Anthropic prompt caching: tokens written to the cache on this call
+     *  (billed at ~1.25× input rate). Undefined for providers that don't
+     *  support caching or for calls below the cache size threshold. */
+    cacheCreationTokens?: number;
+    /** Anthropic prompt caching: tokens read from cache on this call
+     *  (billed at ~0.1× input rate — the big savings live here). */
+    cacheReadTokens?: number;
 }
 export interface SessionTokenStats {
     totalPromptTokens: number;
@@ -18,6 +25,9 @@ interface TokenRecord {
     promptTokens: number;
     completionTokens: number;
     totalTokens: number;
+    /** Anthropic prompt caching breakdown — see TokenUsage. */
+    cacheCreationTokens?: number;
+    cacheReadTokens?: number;
     model: string;
     provider: string;
     /** Authoritative per-call USD from the provider (OpenRouter), if available. */
@@ -59,6 +69,19 @@ export interface ProviderCostBreakdown {
  * Get cost breakdown grouped by provider/model
  */
 export declare function getCostBreakdown(): ProviderCostBreakdown[];
+/**
+ * Aggregate Anthropic prompt-caching stats for the current session.
+ * Returns the breakdown plus an estimate of what the input billing would
+ * have been *without* caching, so we can surface "you saved $X" to the
+ * user.
+ */
+export interface CacheStats {
+    cacheCreationTokens: number;
+    cacheReadTokens: number;
+    /** Sum of estimatedSavings across all Anthropic-priced records. */
+    estimatedSavingsUsd: number;
+}
+export declare function getCacheStats(): CacheStats;
 /**
  * Get session stats
  */

package/dist/utils/tokenTracker.js

@@ -81,6 +81,8 @@ export function recordTokenUsage(usage, model, provider, actualCostUsd) {
         promptTokens: usage.promptTokens,
         completionTokens: usage.completionTokens,
         totalTokens: usage.totalTokens,
+        cacheCreationTokens: usage.cacheCreationTokens,
+        cacheReadTokens: usage.cacheReadTokens,
         model,
         provider,
         actualCostUsd,
@@ -104,10 +106,19 @@ export function extractOpenAIUsage(data) {
  */
 export function extractAnthropicUsage(data) {
     if (data?.usage) {
+        const inputTokens = data.usage.input_tokens || 0;
+        const outputTokens = data.usage.output_tokens || 0;
+        const cacheCreation = data.usage.cache_creation_input_tokens || 0;
+        const cacheRead = data.usage.cache_read_input_tokens || 0;
+        // Anthropic returns input_tokens EXCLUSIVE of cache creation and cache
+        // read tokens — they're reported separately. Total prompt = sum of all
+        // three so our context window math doesn't undercount.
         return {
-            promptTokens: data.usage.input_tokens || 0,
-            completionTokens: data.usage.output_tokens || 0,
-            totalTokens: (data.usage.input_tokens || 0) + (data.usage.output_tokens || 0),
+            promptTokens: inputTokens + cacheCreation + cacheRead,
+            completionTokens: outputTokens,
+            totalTokens: inputTokens + cacheCreation + cacheRead + outputTokens,
+            cacheCreationTokens: cacheCreation || undefined,
+            cacheReadTokens: cacheRead || undefined,
         };
     }
     return null;
@@ -132,13 +143,42 @@ export function getCostBreakdown() {
         else {
             const pricing = MODEL_PRICING[record.model];
             if (pricing) {
-                existing.estimatedCost += (record.promptTokens / 1_000_000) * pricing.inputPer1M + (record.completionTokens / 1_000_000) * pricing.outputPer1M;
+                // Anthropic prompt caching: cache_creation_input is billed at 1.25×
+                // the base input rate, cache_read_input at 0.1×. The remaining
+                // (uncached) prompt tokens bill at the standard 1.0× rate.
+                const cacheCreate = record.cacheCreationTokens ?? 0;
+                const cacheRead = record.cacheReadTokens ?? 0;
+                const uncachedPrompt = Math.max(0, record.promptTokens - cacheCreate - cacheRead);
+                existing.estimatedCost +=
+                    (uncachedPrompt / 1_000_000) * pricing.inputPer1M
+                        + (cacheCreate / 1_000_000) * pricing.inputPer1M * 1.25
+                        + (cacheRead / 1_000_000) * pricing.inputPer1M * 0.1
+                        + (record.completionTokens / 1_000_000) * pricing.outputPer1M;
             }
         }
         grouped.set(key, existing);
     }
     return Array.from(grouped.values());
 }
+export function getCacheStats() {
+    let cacheCreate = 0;
+    let cacheRead = 0;
+    let savings = 0;
+    for (const record of records) {
+        cacheCreate += record.cacheCreationTokens ?? 0;
+        cacheRead += record.cacheReadTokens ?? 0;
+        // Savings = what cache-read tokens would have cost at full input rate,
+        // minus what they actually cost at 0.1×. (Cache creation is a slight
+        // *penalty* of 0.25× — netted in for honest reporting.)
+        const pricing = MODEL_PRICING[record.model];
+        if (pricing) {
+            const cReadSaved = ((record.cacheReadTokens ?? 0) / 1_000_000) * pricing.inputPer1M * 0.9;
+            const cCreateCost = ((record.cacheCreationTokens ?? 0) / 1_000_000) * pricing.inputPer1M * 0.25;
+            savings += cReadSaved - cCreateCost;
+        }
+    }
+    return { cacheCreationTokens: cacheCreate, cacheReadTokens: cacheRead, estimatedSavingsUsd: Math.max(0, savings) };
+}
 /**
  * Get session stats
  */
@@ -207,6 +247,18 @@ export function formatCostReport() {
             lines.push(`| \`${b.provider}\` / \`${b.model}\` | ${formatTokenCount(b.promptTokens)} | ${formatTokenCount(b.completionTokens)} | $${b.estimatedCost.toFixed(4)} |`);
         }
     }
+    // Prompt caching summary — only shown if at least one cached call landed.
+    const cache = getCacheStats();
+    if (cache.cacheReadTokens > 0 || cache.cacheCreationTokens > 0) {
+        lines.push('', '### Prompt caching');
+        lines.push(`**Cache reads:** ${formatTokenCount(cache.cacheReadTokens)} tokens (billed at 0.1× input rate)`);
+        if (cache.cacheCreationTokens > 0) {
+            lines.push(`**Cache writes:** ${formatTokenCount(cache.cacheCreationTokens)} tokens (billed at 1.25× input rate)`);
+        }
+        if (cache.estimatedSavingsUsd > 0) {
+            lines.push(`**Estimated savings vs no caching:** $${cache.estimatedSavingsUsd.toFixed(4)}`);
+        }
+    }
     // Models with no pricing entry don't contribute to cost — flag so users
     // aren't surprised the total looks low.
     const untracked = breakdown.filter(b => b.estimatedCost === 0 && (b.promptTokens + b.completionTokens) > 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeep",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "AI-powered coding assistant built for the terminal. Multiple LLM providers, project-aware context, and a seamless development workflow.",
   "type": "module",
   "main": "dist/index.js",