@phren/agent 0.1.2 → 0.1.3

package/dist/agent-loop.js

@@ -1,6 +1,7 @@
 import { createSpinner, formatTurnHeader, formatToolCall } from "./spinner.js";
 import { searchErrorRecovery } from "./memory/error-recovery.js";
 import { shouldPrune, pruneMessages } from "./context/pruner.js";
+import { estimateMessageTokens } from "./context/token-counter.js";
 import { withRetry } from "./providers/retry.js";
 import { createCaptureState, analyzeAndCapture } from "./memory/auto-capture.js";
 import { AntiPatternTracker } from "./memory/anti-patterns.js";
@@ -133,9 +134,15 @@ export async function runTurn(userInput, session, config, hooks) {
         }
         // Prune context if approaching limit
         if (shouldPrune(systemPrompt, session.messages, { contextLimit })) {
+            const preCount = session.messages.length;
+            const preTokens = estimateMessageTokens(session.messages);
             session.messages = pruneMessages(session.messages, { contextLimit, keepRecentTurns: 6 });
-            if (verbose)
-                status("[context pruned]\n");
+            const postCount = session.messages.length;
+            const postTokens = estimateMessageTokens(session.messages);
+            const reduction = preTokens > 0 ? ((1 - postTokens / preTokens) * 100).toFixed(0) : "0";
+            const fmtPre = preTokens >= 1000 ? `${(preTokens / 1000).toFixed(1)}k` : String(preTokens);
+            const fmtPost = postTokens >= 1000 ? `${(postTokens / 1000).toFixed(1)}k` : String(postTokens);
+            status(`\x1b[2m[context pruned: ${preCount} → ${postCount} messages, ~${fmtPre} → ~${fmtPost} tokens, ${reduction}% reduction]\x1b[0m\n`);
         }
         // For plan mode first turn, pass empty tools so LLM can't call any
         const turnTools = planPending ? [] : toolDefs;

package/dist/commands.js

@@ -4,6 +4,16 @@ import { listPresets, loadPreset, savePreset, deletePreset, formatPreset } from
 import { renderMarkdown } from "./multi/markdown.js";
 import { showModelPicker } from "./multi/model-picker.js";
 import { formatProviderList, formatModelAddHelp, addCustomModel, removeCustomModel } from "./multi/provider-manager.js";
+import { execSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { saveSessionMessages } from "./memory/session.js";
+import { buildIndex } from "@phren/cli/shared";
+import { searchKnowledgeRows, rankResults } from "@phren/cli/shared/retrieval";
+import { readFindings } from "@phren/cli/data/access";
+import { readTasks } from "@phren/cli/data/tasks";
+import { addFinding } from "@phren/cli/core/finding";
 const DIM = "\x1b[2m";
 const BOLD = "\x1b[1m";
 const CYAN = "\x1b[36m";
@@ -19,6 +29,17 @@ export function createCommandContext(session, contextLimit) {
         undoStack: [],
     };
 }
+/** Format elapsed milliseconds as human-readable duration. */
+function formatElapsed(ms) {
+    const secs = Math.floor(ms / 1000);
+    if (secs < 60)
+        return `${secs}s`;
+    const mins = Math.floor(secs / 60);
+    if (mins < 60)
+        return `${mins}m ${secs % 60}s`;
+    const hrs = Math.floor(mins / 60);
+    return `${hrs}h ${mins % 60}m`;
+}
 /** Truncate text to N lines, appending [+M lines] if overflow. */
 function truncateText(text, maxLines) {
     const lines = text.split("\n");
@@ -29,6 +50,7 @@ function truncateText(text, maxLines) {
 }
 /**
  * Try to handle a slash command. Returns true if the input was a command.
+ * Returns a Promise<boolean> for async commands like /ask.
  */
 export function handleCommand(input, ctx) {
     const parts = input.trim().split(/\s+/);
@@ -42,15 +64,28 @@ export function handleCommand(input, ctx) {
   /model remove <id>  Remove a custom model
   /provider   Show configured providers + auth status
   /turns      Show turn and tool call counts
-  /clear      Clear conversation history
+  /clear      Clear conversation history and terminal screen
+  /cwd        Show current working directory
+  /files      Quick file tree (max depth 2, first 30 files)
   /cost       Show token usage and estimated cost
   /plan       Show conversation plan (tool calls so far)
   /undo       Undo last user message and response
   /history [n|full]  Show last N messages (default 10) with rich formatting
   /compact    Compact conversation to save context space
+  /context    Show context window usage and provider info
   /mode       Toggle input mode (steering ↔ queue)
   /spawn <name> <task>  Spawn a background agent
   /agents     List running agents
+  /session    Show session info (id, duration, stats)
+  /session save  Save conversation checkpoint
+  /session export  Export conversation as JSON
+  /diff [--staged]  Show git diff with syntax highlighting
+  /git <cmd>  Run common git commands (status, log, stash, stash pop)
+  /ask <question>  Quick LLM query (no tools, not added to session)
+  /mem search <query>  Search phren memory directly
+  /mem findings [project]  Show recent findings
+  /mem tasks [project]  Show tasks
+  /mem add <finding>  Quick-add a finding
   /preset [name|save|delete|list]  Config presets
   /exit       Exit the REPL${RESET}\n`);
             return true;
@@ -129,8 +164,32 @@ export function handleCommand(input, ctx) {
             ctx.session.turns = 0;
             ctx.session.toolCalls = 0;
             ctx.undoStack.length = 0;
+            process.stdout.write("\x1b[2J\x1b[H"); // clear terminal screen
             process.stderr.write(`${DIM}Conversation cleared.${RESET}\n`);
             return true;
+        case "/cwd":
+            process.stderr.write(`${DIM}${process.cwd()}${RESET}\n`);
+            return true;
+        case "/files": {
+            try {
+                const countRaw = execSync("find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' | wc -l", { encoding: "utf-8", timeout: 5_000, cwd: process.cwd() }).trim();
+                const total = parseInt(countRaw, 10) || 0;
+                const listRaw = execSync("find . -maxdepth 2 -type f -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' | sort | head -30", { encoding: "utf-8", timeout: 5_000, cwd: process.cwd() }).trim();
+                if (!listRaw) {
+                    process.stderr.write(`${DIM}No files found.${RESET}\n`);
+                }
+                else {
+                    const lines = listRaw.split("\n");
+                    const label = total > lines.length ? `${total} files (showing first ${lines.length})` : `${total} files`;
+                    process.stderr.write(`${DIM}${label}\n${listRaw}${RESET}\n`);
+                }
+            }
+            catch (err) {
+                const e = err;
+                process.stderr.write(`${RED}${e.stderr || e.message || "find failed"}${RESET}\n`);
+            }
+            return true;
+        }
         case "/cost": {
             const ct = ctx.costTracker;
             if (ct) {
@@ -234,10 +293,34 @@ export function handleCommand(input, ctx) {
             return true;
         }
         case "/compact": {
-            const before = ctx.session.messages.length;
+            const beforeCount = ctx.session.messages.length;
+            const beforeTokens = estimateMessageTokens(ctx.session.messages);
             ctx.session.messages = pruneMessages(ctx.session.messages, { contextLimit: ctx.contextLimit, keepRecentTurns: 4 });
-            const after = ctx.session.messages.length;
-            process.stderr.write(`${DIM}Compacted: ${before} → ${after} messages.${RESET}\n`);
+            const afterCount = ctx.session.messages.length;
+            const afterTokens = estimateMessageTokens(ctx.session.messages);
+            const reduction = beforeTokens > 0 ? ((1 - afterTokens / beforeTokens) * 100).toFixed(0) : "0";
+            const fmtBefore = beforeTokens >= 1000 ? `${(beforeTokens / 1000).toFixed(1)}k` : String(beforeTokens);
+            const fmtAfter = afterTokens >= 1000 ? `${(afterTokens / 1000).toFixed(1)}k` : String(afterTokens);
+            process.stderr.write(`${DIM}Compacted: ${beforeCount} → ${afterCount} messages (~${fmtBefore} → ~${fmtAfter} tokens, ${reduction}% reduction)${RESET}\n`);
+            return true;
+        }
+        case "/context": {
+            const ctxTokens = estimateMessageTokens(ctx.session.messages);
+            const ctxPct = ctx.contextLimit > 0 ? (ctxTokens / ctx.contextLimit) * 100 : 0;
+            const ctxPctStr = ctxPct.toFixed(1);
+            const ctxWindowK = ctx.contextLimit >= 1000 ? `${(ctx.contextLimit / 1000).toFixed(0)}k` : String(ctx.contextLimit);
+            const ctxTokensStr = ctxTokens >= 1000 ? `~${(ctxTokens / 1000).toFixed(1)}k` : `~${ctxTokens}`;
+            // Progress bar: 10 chars wide
+            const filled = Math.round(ctxPct / 10);
+            const bar = "█".repeat(Math.min(filled, 10)) + "░".repeat(Math.max(10 - filled, 0));
+            const barColor = ctxPct > 80 ? RED : ctxPct > 50 ? YELLOW : GREEN;
+            const providerLabel = ctx.providerName ?? "unknown";
+            const modelLabel = ctx.currentModel ?? "default";
+            process.stderr.write(`${DIM}  Messages: ${ctx.session.messages.length}\n` +
+                `  Tokens: ${ctxTokensStr} / ${ctxWindowK} (${ctxPctStr}%)\n` +
+                `  Provider: ${providerLabel} (${modelLabel})\n` +
+                `  Context window: ${ctxWindowK}\n` +
+                `  ${barColor}[${bar}]${RESET}${DIM} ${ctxPctStr}%${RESET}\n`);
             return true;
         }
         case "/spawn": {
@@ -346,6 +429,270 @@ export function handleCommand(input, ctx) {
             }
             return true;
         }
+        case "/session": {
+            const sub = parts[1]?.toLowerCase();
+            if (sub === "save") {
+                if (!ctx.phrenPath || !ctx.sessionId) {
+                    process.stderr.write(`${DIM}No active phren session to save.${RESET}\n`);
+                    return true;
+                }
+                try {
+                    saveSessionMessages(ctx.phrenPath, ctx.sessionId, ctx.session.messages);
+                    process.stderr.write(`${GREEN}→ Checkpoint saved (${ctx.session.messages.length} messages)${RESET}\n`);
+                }
+                catch (err) {
+                    process.stderr.write(`${RED}${err instanceof Error ? err.message : String(err)}${RESET}\n`);
+                }
+                return true;
+            }
+            if (sub === "export") {
+                const exportDir = path.join(os.homedir(), ".phren-agent", "exports");
+                fs.mkdirSync(exportDir, { recursive: true });
+                const ts = new Date().toISOString().replace(/[:.]/g, "-");
+                const exportFile = path.join(exportDir, `session-${ts}.json`);
+                try {
+                    fs.writeFileSync(exportFile, JSON.stringify(ctx.session.messages, null, 2) + "\n");
+                    process.stderr.write(`${GREEN}→ Exported to ${exportFile}${RESET}\n`);
+                }
+                catch (err) {
+                    process.stderr.write(`${RED}${err instanceof Error ? err.message : String(err)}${RESET}\n`);
+                }
+                return true;
+            }
+            // Default: show session info
+            const duration = ctx.startTime ? formatElapsed(Date.now() - ctx.startTime) : "unknown";
+            const lines = [];
+            if (ctx.sessionId)
+                lines.push(`  Session:  ${ctx.sessionId}`);
+            lines.push(`  Turns:    ${ctx.session.turns}`);
+            lines.push(`  Tools:    ${ctx.session.toolCalls}`);
+            lines.push(`  Messages: ${ctx.session.messages.length}`);
+            lines.push(`  Duration: ${duration}`);
+            // Read session state file for findings/tasks counters
+            if (ctx.phrenPath && ctx.sessionId) {
+                try {
+                    const stateFile = path.join(ctx.phrenPath, ".runtime", "sessions", `session-${ctx.sessionId}.json`);
+                    const state = JSON.parse(fs.readFileSync(stateFile, "utf-8"));
+                    lines.push(`  Findings: ${state.findingsAdded ?? 0}`);
+                    lines.push(`  Tasks:    ${state.tasksCompleted ?? 0}`);
+                }
+                catch { /* session file may not exist */ }
+            }
+            process.stderr.write(`${DIM}${lines.join("\n")}${RESET}\n`);
+            return true;
+        }
+        case "/diff": {
+            const staged = parts.includes("--staged") || parts.includes("--cached");
+            const cmd = staged ? "git diff --staged" : "git diff";
+            try {
+                const raw = execSync(cmd, { encoding: "utf-8", timeout: 10_000, cwd: process.cwd() });
+                if (!raw.trim()) {
+                    process.stderr.write(`${DIM}No ${staged ? "staged " : ""}changes.${RESET}\n`);
+                }
+                else {
+                    const colored = raw.split("\n").map((line) => {
+                        if (line.startsWith("diff --git"))
+                            return `${BOLD}${line}${RESET}`;
+                        if (line.startsWith("@@"))
+                            return `${CYAN}${line}${RESET}`;
+                        if (line.startsWith("+"))
+                            return `${GREEN}${line}${RESET}`;
+                        if (line.startsWith("-"))
+                            return `${RED}${line}${RESET}`;
+                        return line;
+                    }).join("\n");
+                    process.stderr.write(colored + "\n");
+                }
+            }
+            catch (err) {
+                const e = err;
+                process.stderr.write(`${RED}${e.stderr || e.message || "git diff failed"}${RESET}\n`);
+            }
+            return true;
+        }
+        case "/git": {
+            const sub = parts.slice(1).join(" ").trim();
+            if (!sub) {
+                process.stderr.write(`${DIM}Usage: /git <status|log|stash|stash pop>${RESET}\n`);
+                return true;
+            }
+            const allowed = {
+                "status": "git status",
+                "log": "git log --oneline -5",
+                "stash": "git stash",
+                "stash pop": "git stash pop",
+            };
+            const gitCmd = allowed[sub];
+            if (!gitCmd) {
+                process.stderr.write(`${DIM}Supported: /git status, /git log, /git stash, /git stash pop${RESET}\n`);
+                return true;
+            }
+            try {
+                const output = execSync(gitCmd, { encoding: "utf-8", timeout: 10_000, cwd: process.cwd() });
+                if (output.trim())
+                    process.stderr.write(output.endsWith("\n") ? output : output + "\n");
+                else
+                    process.stderr.write(`${DIM}(no output)${RESET}\n`);
+            }
+            catch (err) {
+                const e = err;
+                process.stderr.write(`${RED}${e.stderr || e.message || "git command failed"}${RESET}\n`);
+            }
+            return true;
+        }
+        case "/mem": {
+            const sub = parts[1]?.toLowerCase();
+            if (!ctx.phrenCtx) {
+                process.stderr.write(`${DIM}No phren context available.${RESET}\n`);
+                return true;
+            }
+            const pCtx = ctx.phrenCtx;
+            if (!sub || sub === "help") {
+                process.stderr.write(`${DIM}Usage:
+  /mem search <query>     Search phren memory
+  /mem findings [project] Show recent findings
+  /mem tasks [project]    Show tasks
+  /mem add <finding>      Quick-add a finding${RESET}\n`);
+                return true;
+            }
+            if (sub === "search") {
+                const query = parts.slice(2).join(" ").trim();
+                if (!query) {
+                    process.stderr.write(`${DIM}Usage: /mem search <query>${RESET}\n`);
+                    return true;
+                }
+                return (async () => {
+                    try {
+                        const db = await buildIndex(pCtx.phrenPath, pCtx.profile);
+                        const result = await searchKnowledgeRows(db, {
+                            query,
+                            maxResults: 10,
+                            filterProject: pCtx.project || null,
+                            filterType: null,
+                            phrenPath: pCtx.phrenPath,
+                        });
+                        const ranked = rankResults(result.rows ?? [], query, null, pCtx.project || null, pCtx.phrenPath, db);
+                        if (ranked.length === 0) {
+                            process.stderr.write(`${DIM}No results found.${RESET}\n`);
+                        }
+                        else {
+                            const lines = ranked.slice(0, 10).map((r, i) => {
+                                const snippet = r.content?.slice(0, 200) ?? "";
+                                return `  ${CYAN}${i + 1}.${RESET} ${DIM}[${r.project}/${r.filename}]${RESET} ${snippet}`;
+                            });
+                            process.stderr.write(lines.join("\n") + "\n");
+                        }
+                    }
+                    catch (err) {
+                        process.stderr.write(`${RED}Search failed: ${err instanceof Error ? err.message : String(err)}${RESET}\n`);
+                    }
+                    return true;
+                })();
+            }
+            if (sub === "findings") {
+                const project = parts[2] || pCtx.project;
+                if (!project) {
+                    process.stderr.write(`${DIM}Usage: /mem findings <project>${RESET}\n`);
+                    return true;
+                }
+                const result = readFindings(pCtx.phrenPath, project);
+                if (!result.ok) {
+                    process.stderr.write(`${RED}${result.error}${RESET}\n`);
+                    return true;
+                }
+                const items = result.data ?? [];
+                if (items.length === 0) {
+                    process.stderr.write(`${DIM}No findings for ${project}.${RESET}\n`);
+                    return true;
+                }
+                const recent = items.slice(-15);
+                const lines = recent.map((f) => `  ${DIM}${f.date}${RESET} ${f.text.slice(0, 120)}${f.text.length > 120 ? "..." : ""}`);
+                process.stderr.write(`${DIM}── Findings (${items.length} total, showing last ${recent.length}) ──${RESET}\n`);
+                process.stderr.write(lines.join("\n") + "\n");
+                return true;
+            }
+            if (sub === "tasks") {
+                const project = parts[2] || pCtx.project;
+                if (!project) {
+                    process.stderr.write(`${DIM}Usage: /mem tasks <project>${RESET}\n`);
+                    return true;
+                }
+                const result = readTasks(pCtx.phrenPath, project);
+                if (!result.ok) {
+                    process.stderr.write(`${RED}${result.error}${RESET}\n`);
+                    return true;
+                }
+                const sections = [];
+                for (const [section, items] of Object.entries(result.data.items)) {
+                    if (section === "Done")
+                        continue;
+                    if (items.length === 0)
+                        continue;
+                    const lines = items.map((t) => {
+                        const icon = t.checked ? `${GREEN}✓${RESET}` : `${DIM}○${RESET}`;
+                        return `  ${icon} ${t.line}`;
+                    });
+                    sections.push(`${BOLD}${section}${RESET}\n${lines.join("\n")}`);
+                }
+                if (sections.length === 0) {
+                    process.stderr.write(`${DIM}No active tasks for ${project}.${RESET}\n`);
+                }
+                else {
+                    process.stderr.write(sections.join("\n") + "\n");
+                }
+                return true;
+            }
+            if (sub === "add") {
+                const finding = parts.slice(2).join(" ").trim();
+                if (!finding) {
+                    process.stderr.write(`${DIM}Usage: /mem add <finding text>${RESET}\n`);
+                    return true;
+                }
+                const project = pCtx.project;
+                if (!project) {
+                    process.stderr.write(`${DIM}No project context. Cannot add finding without a project.${RESET}\n`);
+                    return true;
+                }
+                const result = addFinding(pCtx.phrenPath, project, finding);
+                if (result.ok) {
+                    process.stderr.write(`${GREEN}→ Finding saved to ${project}.${RESET}\n`);
+                }
+                else {
+                    process.stderr.write(`${RED}${result.message ?? "Failed to save finding."}${RESET}\n`);
+                }
+                return true;
+            }
+            process.stderr.write(`${DIM}Unknown /mem subcommand: ${sub}. Try /mem help${RESET}\n`);
+            return true;
+        }
+        case "/ask": {
+            const question = parts.slice(1).join(" ").trim();
+            if (!question) {
+                process.stderr.write(`${DIM}Usage: /ask <question>${RESET}\n`);
+                return true;
+            }
+            if (!ctx.provider) {
+                process.stderr.write(`${DIM}Provider not available for /ask.${RESET}\n`);
+                return true;
+            }
+            const provider = ctx.provider;
+            const sysPrompt = ctx.systemPrompt ?? "You are a helpful assistant.";
+            return (async () => {
+                process.stderr.write(`${DIM}◆ quick answer (no tools):${RESET}\n`);
+                try {
+                    const response = await provider.chat(sysPrompt, [{ role: "user", content: question }], []);
+                    for (const block of response.content) {
+                        if (block.type === "text") {
+                            process.stderr.write(renderMarkdown(block.text) + "\n");
+                        }
+                    }
+                }
+                catch (err) {
+                    process.stderr.write(`${RED}${err instanceof Error ? err.message : String(err)}${RESET}\n`);
+                }
+                return true;
+            })();
+        }
         case "/exit":
         case "/quit":
         case "/q":

package/dist/config.js

@@ -11,7 +11,8 @@ Options:
   --max-output <n>     Max output tokens per response (default: auto per model)
   --budget <dollars>   Max spend in USD (aborts when exceeded)
   --plan               Plan mode: show plan before executing tools
-  --permissions <mode> Permission mode: suggest, auto-confirm, full-auto (default: auto-confirm)
+  --permissions <mode> Permission mode: suggest (default), auto-confirm, full-auto
+  --yolo               Full-auto permissions — no confirmations (alias for --permissions full-auto)
   --interactive, -i    Interactive REPL mode (multi-turn conversation)
   --resume             Resume last session's conversation
   --lint-cmd <cmd>     Override auto-detected lint command
@@ -46,7 +47,7 @@ Examples:
 export function parseArgs(argv) {
     const args = {
         task: "",
-        permissions: "auto-confirm",
+        permissions: "suggest",
         maxTurns: 50,
         budget: null,
         plan: false,
@@ -120,6 +121,9 @@ export function parseArgs(argv) {
         else if (arg === "--budget" && argv[i + 1]) {
             args.budget = parseFloat(argv[++i]) || null;
         }
+        else if (arg === "--yolo") {
+            args.permissions = "full-auto";
+        }
         else if (arg === "--permissions" && argv[i + 1]) {
             const mode = argv[++i];
             if (mode === "suggest" || mode === "auto-confirm" || mode === "full-auto") {

package/dist/index.js

@@ -165,6 +165,7 @@ export async function runAgentCli(raw) {
         costTracker,
         plan: args.plan,
         lintTestConfig,
+        sessionId,
     };
     // Multi-agent TUI mode
     if (args.multi || args.team) {

package/dist/multi/spawner.js

@@ -28,6 +28,7 @@ const ENV_FORWARD_KEYS = [
     "PHREN_PROFILE",
     "PHREN_DEBUG",
     "HOME",
+    "USERPROFILE",
     "PATH",
     "NODE_EXTRA_CA_CERTS",
 ];
@@ -160,7 +161,7 @@ export class AgentSpawner extends EventEmitter {
         // Give it a moment to clean up, then force kill
         setTimeout(() => {
             if (this.processes.has(agentId)) {
-                child.kill("SIGTERM");
+                child.kill();
             }
         }, 5000);
         const agent = this.agents.get(agentId);
@@ -207,7 +208,7 @@ export class AgentSpawner extends EventEmitter {
                 setTimeout(() => {
                     // Force kill remaining
                     for (const [id, child] of this.processes) {
-                        child.kill("SIGKILL");
+                        child.kill();
                         this.processes.delete(id);
                     }
                     resolve();

package/dist/permissions/shell-safety.js

@@ -11,6 +11,14 @@ const DANGEROUS_PATTERNS = [
     { pattern: /\bnohup\b/i, reason: "Detached process may outlive session", severity: "block" },
     { pattern: /\bdisown\b/i, reason: "Detached process may outlive session", severity: "block" },
     { pattern: /\bsetsid\b/i, reason: "Detached process may outlive session", severity: "block" },
+    // Block: Windows-specific destructive commands
+    { pattern: /\bformat\s+[a-z]:/i, reason: "Disk format command", severity: "block" },
+    { pattern: /\bdel\s+\/[sq]/i, reason: "Recursive or quiet delete", severity: "block" },
+    { pattern: /\brd\s+\/s/i, reason: "Recursive directory removal", severity: "block" },
+    { pattern: /\brmdir\s+\/s/i, reason: "Recursive directory removal", severity: "block" },
+    { pattern: /\breg\s+delete\b/i, reason: "Registry deletion", severity: "block" },
+    { pattern: /\bpowershell\b.*\b-enc\b/i, reason: "Encoded PowerShell command (obfuscation)", severity: "block" },
+    { pattern: /\bcmd\b.*\/c.*\bdel\s+\/[sq]/i, reason: "Recursive or quiet delete via cmd", severity: "block" },
     // Warn: potentially dangerous
     { pattern: /\beval\b/i, reason: "Dynamic code execution via eval", severity: "warn" },
     { pattern: /\$\(.*\)/, reason: "Command substitution", severity: "warn" },

package/dist/providers/anthropic.js

@@ -4,28 +4,15 @@ export class AnthropicProvider {
     maxOutputTokens;
     apiKey;
     model;
-    constructor(apiKey, model, maxOutputTokens) {
+    cacheEnabled;
+    constructor(apiKey, model, maxOutputTokens, cacheEnabled = true) {
         this.apiKey = apiKey;
         this.model = model ?? "claude-sonnet-4-20250514";
         this.maxOutputTokens = maxOutputTokens ?? 8192;
+        this.cacheEnabled = cacheEnabled;
     }
     async chat(system, messages, tools) {
-        const body = {
-            model: this.model,
-            system,
-            messages: messages.map((m) => ({
-                role: m.role,
-                content: m.content,
-            })),
-            max_tokens: this.maxOutputTokens,
-        };
-        if (tools.length > 0) {
-            body.tools = tools.map((t) => ({
-                name: t.name,
-                description: t.description,
-                input_schema: t.input_schema,
-            }));
-        }
+        const body = this.buildRequestBody(system, messages, tools);
         const res = await fetch("https://api.anthropic.com/v1/messages", {
             method: "POST",
             headers: {
@@ -45,6 +32,7 @@ export class AnthropicProvider {
             : data.stop_reason === "max_tokens" ? "max_tokens"
                 : "end_turn";
         const usage = data.usage;
+        logCacheUsage(usage);
         return {
             content,
             stop_reason: stop_reason,
@@ -52,20 +40,8 @@ export class AnthropicProvider {
         };
     }
     async *chatStream(system, messages, tools) {
-        const body = {
-            model: this.model,
-            system,
-            messages: messages.map((m) => ({ role: m.role, content: m.content })),
-            max_tokens: this.maxOutputTokens,
-            stream: true,
-        };
-        if (tools.length > 0) {
-            body.tools = tools.map((t) => ({
-                name: t.name,
-                description: t.description,
-                input_schema: t.input_schema,
-            }));
-        }
+        const body = this.buildRequestBody(system, messages, tools);
+        body.stream = true;
         const res = await fetch("https://api.anthropic.com/v1/messages", {
             method: "POST",
             headers: {
@@ -129,6 +105,7 @@ export class AnthropicProvider {
             else if (type === "message_start") {
                 const u = data.message?.usage;
                 if (u) {
+                    logCacheUsage(u);
                     usage = {
                         input_tokens: u.input_tokens ?? 0,
                         output_tokens: u.output_tokens ?? 0,
@@ -138,6 +115,66 @@ export class AnthropicProvider {
         }
         yield { type: "done", stop_reason: stopReason, usage };
     }
+    /** Build the request body with optional prompt caching breakpoints. */
+    buildRequestBody(system, messages, tools) {
+        const cache = { cache_control: { type: "ephemeral" } };
+        // System prompt: use content array format with cache_control on the text block
+        const systemValue = this.cacheEnabled
+            ? [{ type: "text", text: system, ...cache }]
+            : system;
+        const mappedMessages = messages.map((m) => ({ role: m.role, content: m.content }));
+        // Mark the last 2 user messages with cache_control for recent-context caching
+        if (this.cacheEnabled) {
+            let marked = 0;
+            for (let i = mappedMessages.length - 1; i >= 0 && marked < 2; i--) {
+                if (mappedMessages[i].role !== "user")
+                    continue;
+                const c = mappedMessages[i].content;
+                if (typeof c === "string") {
+                    mappedMessages[i] = {
+                        role: "user",
+                        content: [{ type: "text", text: c, ...cache }],
+                    };
+                }
+                else if (Array.isArray(c) && c.length > 0) {
+                    // Add cache_control to the last block of the content array
+                    const blocks = [...c];
+                    blocks[blocks.length - 1] = { ...blocks[blocks.length - 1], ...cache };
+                    mappedMessages[i] = { role: "user", content: blocks };
+                }
+                marked++;
+            }
+        }
+        const body = {
+            model: this.model,
+            system: systemValue,
+            messages: mappedMessages,
+            max_tokens: this.maxOutputTokens,
+        };
+        if (tools.length > 0) {
+            const mappedTools = tools.map((t) => ({
+                name: t.name,
+                description: t.description,
+                input_schema: t.input_schema,
+            }));
+            // Cache the last tool definition — Anthropic uses it as the breakpoint for the entire tools block
+            if (this.cacheEnabled) {
+                mappedTools[mappedTools.length - 1] = { ...mappedTools[mappedTools.length - 1], ...cache };
+            }
+            body.tools = mappedTools;
+        }
+        return body;
+    }
+}
+/** Log cache hit/creation stats to stderr (visible in verbose mode). */
+function logCacheUsage(usage) {
+    if (!usage)
+        return;
+    const created = usage.cache_creation_input_tokens;
+    const read = usage.cache_read_input_tokens;
+    if (created || read) {
+        process.stderr.write(`[cache] created=${created ?? 0} read=${read ?? 0} input=${usage.input_tokens ?? 0}\n`);
+    }
 }
 /** Parse SSE stream from a fetch Response. */
 async function* parseSSE(res) {