atom-agent 1.0.0 → 1.1.0

package/dist/agent/normalize.js

@@ -0,0 +1,144 @@
+// Safety net for custom executors (built-in tools already cap: read 64KB
+// head + truncation note + overflow pointer ≈ 66KB, bash 8KB, webfetch 64KB
+// + notes). The cap sits at 128KB so legitimate built-in outputs (overflow
+// pointers included) pass through byte-identical; only oversized custom
+// results truncate.
+export const TOOL_RESULT_CAP_CHARS = 128 * 1024;
+export function normalizeToolResult(result) {
+    let text;
+    if (typeof result === "string") {
+        text = result;
+    }
+    else if (result === null || result === undefined) {
+        return "Error: tool returned no result";
+    }
+    else {
+        try {
+            const json = JSON.stringify(result);
+            text = typeof json === "string" ? json : String(result);
+        }
+        catch {
+            try {
+                text = String(result);
+            }
+            catch {
+                return "Error: tool returned an unreadable result";
+            }
+        }
+    }
+    if (text.length > TOOL_RESULT_CAP_CHARS) {
+        return (text.slice(0, TOOL_RESULT_CAP_CHARS) +
+            `\n[truncated: tool result exceeded ${TOOL_RESULT_CAP_CHARS} chars]`);
+    }
+    return text;
+}
+// Recursively key-sorted JSON for stable signatures. Falls back to a short
+// type tag when unstringifiable (never throws, never aliases objects with
+// strings: prefixes the tag).
+function stableStringify(value) {
+    try {
+        return JSON.stringify(sortKeys(value)) ?? "undefined";
+    }
+    catch {
+        return `unstringifiable:${typeof value}`;
+    }
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (typeof value === "object" && value !== null) {
+        const out = {};
+        for (const k of Object.keys(value).sort()) {
+            out[k] = sortKeys(value[k]);
+        }
+        return out;
+    }
+    return value;
+}
+// Stable repetition/cache key: `name` + canonical args. Parsed args come
+// from JSON.parse (insertion-ordered), so sorting closes the alias where
+// `{"a":1,"b":2}` and `{"b":2,"a":1}` would otherwise count as different.
+export function toolSignature(name, parsed) {
+    return `${name} ${stableStringify(parsed ?? {})}`;
+}
+// Defensive validation of one assistant message. Never throws: malformed
+// tool_calls entries are dropped with a warning (the caller surfaces them
+// via onWarning so the transcript shows what the model attempted); a fully
+// unusable message becomes empty final text (the loop's turn-end gates then
+// decide, exactly as if the model sent empty content).
+export function normalizeChatResult(raw) {
+    const warnings = [];
+    if (typeof raw !== "object" || raw === null) {
+        return { result: { content: null }, warnings: ["model returned a non-object message"] };
+    }
+    const m = raw;
+    const contentRaw = m["content"];
+    const content = typeof contentRaw === "string"
+        ? contentRaw
+        : contentRaw === null || contentRaw === undefined
+            ? null
+            : (() => {
+                try {
+                    return JSON.stringify(contentRaw);
+                }
+                catch {
+                    return String(contentRaw);
+                }
+            })();
+    const callsRaw = m["calls"] ?? m["tool_calls"];
+    if (callsRaw === undefined) {
+        const result = { content };
+        if (m["usage"] !== undefined)
+            result["usage"] = m["usage"];
+        if (m["reasoning"] !== undefined)
+            result["reasoning"] = m["reasoning"];
+        return { result: result, warnings };
+    }
+    if (!Array.isArray(callsRaw)) {
+        warnings.push("model tool_calls was not an array — ignored");
+        return { result: { content, tool_calls: undefined }, warnings };
+    }
+    const calls = [];
+    for (let i = 0; i < callsRaw.length; i++) {
+        const entry = callsRaw[i];
+        if (typeof entry !== "object" || entry === null) {
+            warnings.push(`dropped malformed tool call at index ${i} (not an object)`);
+            continue;
+        }
+        const fn = entry["function"];
+        const name = fn?.["name"];
+        if (typeof name !== "string" || name.length === 0) {
+            const id = typeof entry["id"] === "string" ? entry["id"] : `#${i}`;
+            warnings.push(`dropped tool call ${id} with no function name`);
+            continue;
+        }
+        const id = typeof entry["id"] === "string" && entry["id"].length > 0
+            ? entry["id"]
+            : `call-${i}`;
+        const argsRaw = fn?.["arguments"];
+        let args;
+        if (typeof argsRaw === "string")
+            args = argsRaw;
+        else if (argsRaw === undefined || argsRaw === null)
+            args = "{}";
+        else {
+            try {
+                args = JSON.stringify(argsRaw) ?? "{}";
+            }
+            catch {
+                warnings.push(`dropped tool call ${id} with unstringifiable arguments`);
+                continue;
+            }
+        }
+        const call = { id, function: { name, arguments: args } };
+        if (typeof entry["type"] === "string")
+            call.type = entry["type"];
+        calls.push(call);
+    }
+    const out = { content, tool_calls: calls.length > 0 ? calls : undefined };
+    if (m["usage"] !== undefined)
+        out["usage"] = m["usage"];
+    if (m["reasoning"] !== undefined)
+        out["reasoning"] = m["reasoning"];
+    return { result: out, warnings };
+}

package/dist/cli.js

@@ -60,7 +60,7 @@ Env:
   OPENAI_API_KEY / ANTHROPIC_API_KEY / DEEPSEEK_API_KEY / MISTRAL_API_KEY / GEMINI_API_KEY (GOOGLE_API_KEY alias)  optional per provider (env wins over stored)
   OPENCODE_ZEN_MODEL    optional (default: ${DEFAULT_MODEL}; when set, wins over the saved /model)
   OPENCODE_ZEN_ENDPOINT optional (default: ${DEFAULT_ENDPOINT})
-Commands: /model (model picker) | /models [refresh] (local discovery refresh; Kilo catalog refresh when Kilo is active) | /provider (provider + key picker) | /effort (reasoning-effort picker) | /tools | /skills (list installed skills) | /skill:name (invoke) | /context (context usage) | /queue + /steer (follow-ups while busy) | /mode | /clear | /resume (restore last saved session) | /help | /exit | /quit — Tab cycles the permission mode normal → yolo → plan
+Commands: /model (model picker) | /models [refresh] (local discovery refresh; Kilo catalog refresh when Kilo is active) | /provider (provider + key picker) | /effort (reasoning-effort picker) | /tools | /skills (list installed skills) | /skill:name (invoke) | /context (context usage) | /queue + /steer (follow-ups while busy) | /autoscroll on|off (follow new output) | /thinking (toggle reasoning visibility) | /mode | /clear | /resume (restore last saved session) | /help | /exit | /quit — Tab cycles the permission mode normal → yolo → plan
 Providers: kilo (default; anonymous free models, key optional)/opencode-zen/openai/anthropic/deepseek/mistral/google-gemini/openai-compatible (keys in ~/.atom/auth.json, 0600 POSIX; use /provider to paste one) + local auto-discovery: ollama (:11434), lmstudio (:1234), llamacpp (:8080) — no keys needed, overrides via ATOM_OLLAMA_URL/ATOM_LMSTUDIO_URL/ATOM_LLAMACPP_URL.
 Note: reasoning_effort is sent only for opencode-zen supported models.`);
     process.exit(0);

package/dist/system.js

@@ -21,6 +21,7 @@ export const SYSTEM_PROMPT = [
     "Prefer the smallest correct change. Fix root causes. Handle errors and edge cases. Remove dead code.",
     "Ground every claim in tool output, never in memory. Run commands to check facts.",
     "After each tool result, reflect briefly, then take the best next action toward the goal.",
+    "Batch independent work in one block: parallel-safe reads and searches in the same response run concurrently and finish in a single round-trip — one call per response is the slow path.",
     "Keep calling tools until verified done. Never end on an unverified summary or a guess.",
     "Done means tests and typecheck pass, or the blocker is named with its evidence.",
     "",

package/dist/telemetry-dashboard.js

@@ -246,12 +246,28 @@ function iterationTimeline(s) {
 function turnBlock(t) {
     const outcomeCls = t.outcome === "completed" ? "ok" : t.outcome === "failed" ? "err" : "warn";
     const total = turnTokensTotal(t);
+    // Loop-harness rollup (present only when the loop reported stats for this
+    // turn — older sessions render exactly as before).
+    const loopBits = [];
+    if (t.loop) {
+        if (t.loop.cacheHits > 0)
+            loopBits.push(`read-cache hits ${fmtCount(t.loop.cacheHits)}`);
+        if (t.loop.repetitionHits > 0)
+            loopBits.push(`loop-guard hits ${fmtCount(t.loop.repetitionHits)}`);
+        if (t.loop.bottleneckName) {
+            loopBits.push(`bottleneck ${escapeHtml(t.loop.bottleneckName)}` +
+                (t.loop.bottleneckMs !== undefined ? ` ${fmtMs(t.loop.bottleneckMs)}` : ""));
+        }
+        if (t.loop.truncations > 0)
+            loopBits.push(`truncated ${fmtCount(t.loop.truncations)} turn(s)`);
+    }
     const head = `<span class="${outcomeCls}">${escapeHtml(t.outcome)}</span>` +
         ` · ${fmtMs(t.durationMs)}` +
         ` · ${t.modelCalls.length} model call(s)` +
         ` · ${t.toolCalls.length} tool call(s)` +
         ` · retries ${t.retryCount}` +
-        ` · tokens ${total !== null ? fmtCount(total) : `<span class="na" title="No model call in this turn reported usage.">n/a</span>`}`;
+        ` · tokens ${total !== null ? fmtCount(total) : `<span class="na" title="No model call in this turn reported usage.">n/a</span>`}` +
+        (loopBits.length > 0 ? ` · ${loopBits.join(" · ")}` : "");
     return `<details class="turn" data-outcome="${escapeHtml(t.outcome)}">
     <summary><span class="mono">${escapeHtml(t.id)}</span> · ${fmtTime(t.startedAt)} · ${escapeHtml(t.provider)} · ${escapeHtml(t.model)} · ${head}</summary>
     <div class="turnbody">
@@ -488,6 +504,8 @@ ${corruptNote}
 <div class="card"><div class="k">Completion tokens (reported)</div><div class="v">${fmtTokens(agg.usage.completion_tokens, agg.usageReported, "No model call reported completion_tokens.")}</div></div>
 <div class="card"><div class="k">Cache read / write (reported)</div><div class="v">${fmtTokens(agg.usage.cacheReadTokens, agg.usageReported, "No provider reported cache-read counters.")} / ${fmtTokens(agg.usage.cacheWriteTokens, agg.usageReported, "No provider reported cache-write counters.")}</div></div>
 <div class="card"><div class="k">Retries</div><div class="v">${fmtCount(agg.retries)}</div></div>
+<div class="card"><div class="k">Read-cache hits (local)</div><div class="v">${fmtCount(agg.cacheHits)}</div></div>
+<div class="card"><div class="k">Loop-guard hits</div><div class="v">${fmtCount(agg.repetitionHits)}</div></div>
 <div class="card"><div class="k">Avg model latency</div><div class="v">${fmtMs(agg.avgModelLatencyMs)}</div></div>
 <div class="card"><div class="k">Avg tool duration</div><div class="v">${fmtMs(agg.avgToolDurationMs)}</div></div>
 <div class="card"><div class="k">Total cost</div><div class="v"><span class="na" title="${escapeHtml(agg.costNote)}">n/a</span></div></div>

package/dist/telemetry.js

@@ -436,6 +436,8 @@ export function summarizeTelemetry(sessions) {
         compactionUsage: {},
         compactionReported: false,
         retries: 0,
+        cacheHits: 0,
+        repetitionHits: 0,
         outcomes: emptyOutcomes(),
         byTool: [],
         avgModelLatencyMs: null,
@@ -465,6 +467,14 @@ export function summarizeTelemetry(sessions) {
                         agg.usageReported = true;
                 }
                 agg.retries += typeof t.retryCount === "number" ? t.retryCount : 0;
+                if (t.loop) {
+                    if (typeof t.loop.cacheHits === "number" && t.loop.cacheHits > 0) {
+                        agg.cacheHits += Math.floor(t.loop.cacheHits);
+                    }
+                    if (typeof t.loop.repetitionHits === "number" && t.loop.repetitionHits > 0) {
+                        agg.repetitionHits += Math.floor(t.loop.repetitionHits);
+                    }
+                }
                 if (Array.isArray(t.modelCalls)) {
                     for (const m of t.modelCalls) {
                         agg.modelCalls += 1;
@@ -782,6 +792,51 @@ export class TelemetryRecorder {
             // never throw
         }
     }
+    // Attach the loop-harness per-turn rollup (LoopStats from the agent loop,
+    // wired via AgenticOpts.onLoopStats in the App). Merges onto the open turn;
+    // later reports overwrite (the loop reports once, but a retry-safe merge
+    // keeps the newest). No-op when disabled, unknown turn, or bad input.
+    // Never throws. Safe to call before endTurn (success path) — endTurn keeps
+    // turn.loop intact; failed/cancelled turns keep it too (what was attempted).
+    recordLoopStats(turnId, summary) {
+        try {
+            if (!this.enabled || !turnId)
+                return;
+            const turn = this.openTurns.get(turnId);
+            if (!turn)
+                return;
+            if (typeof summary !== "object" || summary === null)
+                return;
+            const s = summary;
+            const num = (v) => typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.floor(v) : undefined;
+            const signed = (v) => typeof v === "number" && Number.isFinite(v) ? Math.floor(v) : undefined;
+            const loop = {
+                cacheHits: num(s["cacheHits"]) ?? 0,
+                repetitionHits: num(s["repetitionHits"]) ?? 0,
+                failures: num(s["failures"]) ?? 0,
+                truncations: num(s["truncationNotices"] ?? s["truncations"]) ?? 0,
+                contextGrowthChars: signed(s["contextGrowthChars"]) ?? 0,
+                loopDurationMs: num(s["durationMs"] ?? s["loopDurationMs"]) ?? 0,
+            };
+            const bottleneck = s["bottleneck"];
+            const bName = typeof bottleneck?.["name"] === "string" ? bottleneck["name"] : undefined;
+            const bMs = num(bottleneck?.["durationMs"] ?? bottleneck?.["ms"] ?? s["bottleneckMs"]) ?? undefined;
+            if (bName && bName.length > 0) {
+                loop.bottleneckName = bName.slice(0, 80);
+                if (bMs !== undefined)
+                    loop.bottleneckMs = bMs;
+            }
+            else if (typeof s["bottleneckName"] === "string" && s["bottleneckName"].length > 0) {
+                loop.bottleneckName = s["bottleneckName"].slice(0, 80);
+                if (bMs !== undefined)
+                    loop.bottleneckMs = bMs;
+            }
+            turn.loop = loop;
+        }
+        catch {
+            // never throw
+        }
+    }
     upsertIteration(turn, step, modelCallId, toolCallId) {
         try {
             let iter = turn.iterations.find((i) => i.step === step);

package/dist/tools/dir-cache.js

@@ -0,0 +1,207 @@
+// Fast directory enumeration for search tools (grep/glob).
+//
+// Problem (measured): every grep/glob recursively walked the repo and
+// stated every entry — ~360ms per glob and ~2s per grep on a 3000-file
+// tree, paid on EVERY call. Two fixes, both behavior-preserving:
+//
+// 1. git fast path: `git ls-files` (tracked) + `--others --exclude-standard`
+//    (untracked, non-ignored) lists the same tree without recursion and
+//    skips ignored build output. Verified: both spellings emit paths
+//    relative to the working directory they run in. Untracked source files
+//    ARE included (no "new file invisible" regression); SKIP_DIRS segments
+//    (node_modules/.git) are filtered after, so the "never searched"
+//    contract holds even for tracked junk. Any failure (non-git dir, no git
+//    binary, timeout) falls back to the recursive walker byte-identically.
+// 2. mtime-checked listing cache + exact invalidation: a cached listing is
+//    reused only while the directory mtime is unchanged, AND every
+//    in-process mutation path invalidates (write/edit drop ancestor listings
+//    — nested creates don't move the parent mtime, so mtime alone is NOT
+//    enough; any bash execution clears all — a command can touch anything).
+//    Only out-of-process edits (user's editor between calls) stay TTL-bound
+//    (15s), documented and accepted: all tool-driven flows are exact.
+//
+// Deliberate non-goal: no ripgrep binary dependency. Measured `rg --files`
+// spawn alone costs ~80ms on Windows — slower than the walker on typical
+// repos — with regex-dialect and hidden/ignore parity risks. Revisit only if
+// walker numbers stay slow after this (they don't — see benchmarks).
+//
+// Kill switch: ATOM_FAST_LIST=0 forces the legacy walker every time.
+// Best-effort throughout; never throws across the tool boundary.
+import { execFile } from "node:child_process";
+import { promises as fsp } from "node:fs";
+import * as path from "node:path";
+import { SKIP_DIRS } from "./shared.js";
+const LISTING_TTL_MS = 15_000;
+const LISTING_MAX_ENTRIES = 50;
+const GIT_TIMEOUT_MS = 15_000;
+const listingCache = new Map();
+const cacheStats = { hits: 0, misses: 0, stores: 0, gitUses: 0, walkerUses: 0 };
+export function fastListEnabled() {
+    const raw = process.env.ATOM_FAST_LIST;
+    if (raw === undefined)
+        return true;
+    const v = raw.trim().toLowerCase();
+    return !(v === "0" || v === "false" || v === "no" || v === "off");
+}
+// Recursive walker (legacy contract): cwd-relative posix paths, SKIP_DIRS
+// pruned, files only. Used directly when the fast path is off/unavailable.
+export async function walkFiles(absDir, cwd, out) {
+    const entries = await fsp.readdir(absDir, { withFileTypes: true });
+    for (const e of entries) {
+        if (SKIP_DIRS.has(e.name))
+            continue;
+        const full = path.join(absDir, e.name);
+        if (e.isDirectory()) {
+            await walkFiles(full, cwd, out);
+        }
+        else if (e.isFile()) {
+            out.push(path.relative(cwd, full).split(path.sep).join("/"));
+        }
+    }
+}
+function gitFile(args, cwd) {
+    return new Promise((resolve, reject) => {
+        execFile("git", args, { cwd, timeout: GIT_TIMEOUT_MS, windowsHide: true }, (err, stdout) => {
+            if (err) {
+                reject(err instanceof Error ? err : new Error(String(err)));
+                return;
+            }
+            resolve(typeof stdout === "string" ? stdout : String(stdout ?? ""));
+        });
+    });
+}
+function toCwdRel(absDir, cwd, dirRel) {
+    const prefix = path.relative(cwd, absDir).split(path.sep).join("/");
+    if (!prefix || prefix === ".")
+        return dirRel;
+    return `${prefix}/${dirRel}`;
+}
+function filterSkipped(relPaths) {
+    return relPaths.filter((rel) => {
+        if (!rel)
+            return false;
+        for (const seg of rel.split("/")) {
+            if (SKIP_DIRS.has(seg))
+                return false;
+        }
+        return true;
+    });
+}
+// Git enumeration: tracked + untracked-non-ignored in ONE invocation, as
+// cwd-relative posix paths. Verified: both spellings emit paths relative to
+// the directory git runs in. Outside a repo (or no git binary) the command
+// fails and this returns null — the caller falls back to the walker.
+async function gitListFiles(absDir, cwd) {
+    let raw;
+    try {
+        raw = await gitFile(["ls-files", "-z", "--cached", "--others", "--exclude-standard"], absDir);
+    }
+    catch {
+        return null;
+    }
+    try {
+        const seen = new Set();
+        const out = [];
+        for (const entry of raw.split("\0")) {
+            if (!entry)
+                continue;
+            const rel = toCwdRel(absDir, cwd, entry.split(path.sep).join("/"));
+            if (!seen.has(rel)) {
+                seen.add(rel);
+                out.push(rel);
+            }
+        }
+        return filterSkipped(out);
+    }
+    catch {
+        return null;
+    }
+}
+async function dirMtimeMs(absDir) {
+    try {
+        return (await fsp.stat(absDir)).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+// List files under absDir as cwd-relative posix paths (walkFiles contract).
+// Fast path: mtime-validated cache → git enumeration → walker fallback.
+// Walker results cache too (the mtime check is equally valid for them).
+export async function listFiles(absDir, cwd) {
+    const key = `${cwd}\n${absDir}`;
+    if (fastListEnabled()) {
+        const mtime = await dirMtimeMs(absDir);
+        const hit = listingCache.get(key);
+        if (hit && mtime !== null && hit.mtimeMs === mtime && Date.now() - hit.storedAt < LISTING_TTL_MS) {
+            // LRU refresh.
+            listingCache.delete(key);
+            listingCache.set(key, hit);
+            cacheStats.hits += 1;
+            return [...hit.entries];
+        }
+        cacheStats.misses += 1;
+        const git = await gitListFiles(absDir, cwd);
+        if (git !== null) {
+            cacheStats.gitUses += 1;
+            storeListing(key, git, mtime);
+            return [...git];
+        }
+    }
+    cacheStats.walkerUses += 1;
+    const out = [];
+    await walkFiles(absDir, cwd, out);
+    if (fastListEnabled()) {
+        storeListing(key, out, await dirMtimeMs(absDir));
+    }
+    return out;
+}
+function storeListing(key, entries, mtimeMs) {
+    try {
+        listingCache.delete(key);
+        while (listingCache.size >= LISTING_MAX_ENTRIES) {
+            const oldest = listingCache.keys().next();
+            if (oldest.done)
+                break;
+            listingCache.delete(oldest.value);
+        }
+        listingCache.set(key, { entries: [...entries], mtimeMs: mtimeMs ?? -1, storedAt: Date.now() });
+        cacheStats.stores += 1;
+    }
+    catch {
+        // cache failures never break search
+    }
+}
+export function clearDirListingCache() {
+    listingCache.clear();
+}
+// Drop every listing whose directory is the file itself or an ancestor of it
+// (a mutation inside the tree can change the listing). Called by write/edit
+// next to the read-cache invalidation. Never throws.
+export function invalidateListingsForFile(absFilePath) {
+    try {
+        if (typeof absFilePath !== "string" || absFilePath.length === 0)
+            return;
+        const target = path.resolve(absFilePath);
+        for (const key of [...listingCache.keys()]) {
+            const splitAt = key.indexOf("\n");
+            const absDir = splitAt >= 0 ? key.slice(splitAt + 1) : key;
+            if (target === absDir || target.startsWith(absDir + path.sep)) {
+                listingCache.delete(key);
+            }
+        }
+    }
+    catch {
+        // never throw across the tool boundary
+    }
+}
+export function getDirListingStats() {
+    return { ...cacheStats, size: listingCache.size };
+}
+export function resetDirListingStats() {
+    cacheStats.hits = 0;
+    cacheStats.misses = 0;
+    cacheStats.stores = 0;
+    cacheStats.gitUses = 0;
+    cacheStats.walkerUses = 0;
+}

package/dist/tools/filesystem.js

@@ -5,6 +5,8 @@ import * as path from "node:path";
 import { capturePriorBytes } from "../snapshots.js";
 import { contentHash, fingerprintKey, readFingerprints } from "./fingerprints.js";
 import { appendOverflow } from "./overflow.js";
+import { getCachedRead, invalidatePath, normalizeReadWindow, setCachedRead } from "./read-cache.js";
+import { invalidateListingsForFile } from "./dir-cache.js";
 import { err, invalidCall, READ_CHAR_CAP, resolveSandbox } from "./shared.js";
 // offset/limit are 1-based line numbers. Output capped at ~64KB.
 export async function readTool(args, cwd = process.cwd()) {
@@ -24,6 +26,21 @@ export async function readTool(args, cwd = process.cwd()) {
             const lines = entries.map((e) => (e.isDirectory() ? `${e.name}/` : e.name));
             return `Directory listing for ${args.path}:\n${lines.join("\n")}`;
         }
+        // Read-cache fast path: same abs + window + unchanged mtime/size skips
+        // disk I/O. The stored hash refreshes the stale-read fingerprint so
+        // read→read→edit chains keep working without re-hashing.
+        const { offset: normOffset, limit: normLimit } = normalizeReadWindow(args.offset, args.limit);
+        try {
+            const statInfo = { mtimeMs: st.mtimeMs ?? 0, size: st.size ?? 0 };
+            const hit = getCachedRead(r.abs, normOffset, normLimit, statInfo);
+            if (hit) {
+                readFingerprints.set(fingerprintKey(r.abs), hit.hash);
+                return hit.result;
+            }
+        }
+        catch {
+            // cache lookup never breaks reads
+        }
         let text;
         try {
             text = await fsp.readFile(r.abs, "utf8");
@@ -31,7 +48,8 @@ export async function readTool(args, cwd = process.cwd()) {
         catch {
             return err(`cannot read file: ${args.path}`);
         }
-        readFingerprints.set(fingerprintKey(r.abs), contentHash(text));
+        const hash = contentHash(text);
+        readFingerprints.set(fingerprintKey(r.abs), hash);
         if (text.length === 0)
             return "";
         const offset = Math.max(1, Math.floor(args.offset ?? 1));
@@ -42,6 +60,13 @@ export async function readTool(args, cwd = process.cwd()) {
             const full = out;
             out = appendOverflow(full.slice(0, READ_CHAR_CAP), "\n[truncated: output exceeded 64KB]", "file output", full);
         }
+        try {
+            const statInfo = { mtimeMs: st.mtimeMs ?? 0, size: st.size ?? 0 };
+            setCachedRead(r.abs, normOffset, normLimit, out, statInfo, hash);
+        }
+        catch {
+            // cache store never breaks reads
+        }
         return out;
     }
     catch (e) {
@@ -61,6 +86,13 @@ export async function writeTool(args, cwd = process.cwd()) {
         await fsp.mkdir(path.dirname(r.abs), { recursive: true });
         await fsp.writeFile(r.abs, args.content, "utf8");
         readFingerprints.set(fingerprintKey(r.abs), contentHash(args.content));
+        try {
+            invalidatePath(r.abs);
+            invalidateListingsForFile(r.abs);
+        }
+        catch {
+            // cache invalidation never breaks writes
+        }
         return `Wrote ${Buffer.byteLength(args.content, "utf8")} bytes to ${args.path}`;
     }
     catch (e) {
@@ -102,6 +134,13 @@ export async function editTool(args, cwd = process.cwd()) {
         await capturePriorBytes(r.abs, `edit ${args.path}`);
         await fsp.writeFile(r.abs, next, "utf8");
         readFingerprints.set(key, contentHash(next));
+        try {
+            invalidatePath(r.abs);
+            invalidateListingsForFile(r.abs);
+        }
+        catch {
+            // cache invalidation never breaks edits
+        }
         return `Edited ${args.path}: replaced ${args.replaceAll ? count : 1} occurrence(s)`;
     }
     catch (e) {