@stitchdb/cli 0.7.3 → 0.7.4

package/dist/cli.js

@@ -490,9 +490,11 @@ async function cmdHook(args) {
         await handlePreReadHook(cfg, event, cwd || process.cwd()).catch(() => { });
         return;
     }
-    // ── PostToolUse on Read: opportunistically save a fresh summary ───────
-    if (eventName === 'PostToolUse' && event?.tool_name === 'Read') {
-        await handlePostReadHook(cfg, event, cwd || process.cwd()).catch(() => { });
+    // ── PostToolUse on Read/Edit/Write/MultiEdit: keep the file-summary
+    //    cache fresh. After an edit we re-hash the on-disk file and
+    //    re-summarise, so a stale "old version" memory never lingers.
+    if (eventName === 'PostToolUse' && ['Read', 'Edit', 'Write', 'MultiEdit'].includes(String(event?.tool_name))) {
+        await handlePostFileChangeHook(cfg, event, cwd || process.cwd()).catch(() => { });
         return;
     }
     // ── SessionStart: self-heal hook config + inject prior context ─────────
@@ -735,13 +737,14 @@ function lastAssistantTextFromTranscript(transcriptPath) {
 const FILE_SUMMARY_MIN_BYTES = 500; // skip tiny files
 const FILE_SUMMARY_MAX_BYTES = 200_000; // skip absolutely huge files
 const FILE_SUMMARY_COOLDOWN_MS = 5 * 60_000; // per-file: don't re-summarize more than once per 5 min
-const FILE_SUMMARY_PROMPT = `You are summarising a single source file for an AI coding assistant cache.
+const FILE_SUMMARY_PROMPT = `You are summarising a single source file for an AI coding assistant's persistent project cache. Other agents will read this summary before deciding whether to open the file in full, so it must enable a real mental model of the project — not just describe the file in isolation.
 
-Return ONLY a 2-3 sentence summary describing:
-  • What the file does (purpose, the few exported symbols / commands / endpoints worth knowing).
-  • Any important pattern, convention, or non-obvious behaviour another agent would benefit from before reading the file in full.
+Return ONLY a 2-4 sentence summary that covers:
+  1. PURPOSE — what this file does, its key exported symbols / routes / commands / classes worth knowing, any non-obvious invariant or pattern.
+  2. CONNECTIONS — concrete other files/modules this depends on (real import paths, real symbol names) AND who/what typically depends on this. Use real names from the file content; don't generalise.
+  3. WHEN TO OPEN — what kind of task forces an edit here vs a peek. (e.g. "edit this when adding a new auth provider; safe to skip for purely UI changes").
 
-Skip preamble. Skip "this file …". Be specific. No markdown fences. No prose around it.
+Be dense and specific. No preamble. No "this file ...". No markdown fences. No prose around it. Plain text only.
 
 File path: {{PATH}}
 
@@ -820,47 +823,64 @@ async function handlePreReadHook(cfg, event, cwd) {
     const payload = { hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: note } };
     process.stdout.write(JSON.stringify(payload));
 }
-// PostToolUse on Read: kick off a background `claude -p` to summarize this
-// file IF we don't already have a summary at the current hash. Fire-and-forget.
-async function handlePostReadHook(cfg, event, cwd) {
+// PostToolUse handler for tools that observe-or-modify a single file
+// (Read, Edit, Write, MultiEdit). Kicks off a background `claude -p` to
+// (re-)summarise this file unless we already have an up-to-date cached
+// summary for this exact hash. Fire-and-forget.
+//
+// Read flow:    file content same as cache → no-op. Different → re-summarise.
+// Edit flow:    file content always different from cache → re-summarise. The
+//               existing summary is replaced by cmdSummarizeFile so no stale
+//               memory persists.
+// Write/MultiEdit: same as Edit.
+//
+// A 30 s "min-interval" floor on top of the hash-keyed cooldown prevents a
+// flurry of edits within seconds from spawning N parallel claude -p calls
+// for the same file.
+async function handlePostFileChangeHook(cfg, event, cwd) {
     const filePath = String(event?.tool_input?.file_path || '');
     if (!filePath)
         return;
     const rel = relPathFor(cwd, filePath);
-    const content = readFileContentFromHookEvent(event);
-    // Fall back to reading from disk if hook payload didn't carry content.
-    let body = content;
-    if (!body) {
-        try {
-            body = fs.readFileSync(filePath, 'utf8');
-        }
-        catch {
-            return;
-        }
+    // After Edit/Write the on-disk content is what we want; the hook payload
+    // may also carry it, but reading from disk is always correct.
+    let body = '';
+    try {
+        body = fs.readFileSync(filePath, 'utf8');
+    }
+    catch {
+        return;
     }
-    if (!body || body.length < FILE_SUMMARY_MIN_BYTES)
+    if (!body)
+        return;
+    // Tiny files: not worth a summary. Huge files: skip; would exhaust context.
+    if (body.length < FILE_SUMMARY_MIN_BYTES)
         return;
     if (body.length > FILE_SUMMARY_MAX_BYTES)
         return;
     const fullHash = await sha256Hex(body);
     const hashPrefix = fullHash.slice(0, 16);
-    // Per-file cooldown so a hot-edited file doesn't re-summarize on every read.
     const state = loadFileSummaryState();
     const last = state.files[rel];
+    // Hash-keyed dedupe: same content as last spawn → nothing to do.
     if (last && last.hash === hashPrefix && Date.now() - last.lastSummarizedAt < FILE_SUMMARY_COOLDOWN_MS)
         return;
+    // Min-interval floor: regardless of hash change, don't spawn more often
+    // than once per 30 s for the same file (catches edit flurries).
+    const MIN_RESPAWN_MS = 30_000;
+    if (last && Date.now() - last.lastSummarizedAt < MIN_RESPAWN_MS)
+        return;
+    // Optimisation: confirm the API view is also stale before spending tokens.
     const stitch = client(cfg);
     const cached = await lookupFileSummary(stitch, rel);
     if (cached && cached.hash === hashPrefix) {
-        // Already summarized this exact version — refresh cooldown and bail.
         state.files[rel] = { hash: hashPrefix, lastSummarizedAt: Date.now() };
         saveFileSummaryState(state);
         return;
     }
-    // Mark BEFORE spawning so a flurry of Read events doesn't fire N spawns.
+    // Mark BEFORE spawning so overlapping events don't fire N spawns.
     state.files[rel] = { hash: hashPrefix, lastSummarizedAt: Date.now() };
     saveFileSummaryState(state);
-    // Spawn detached: stitch _summarize-file <abs-path> <hash> <rel>
     try {
         const cliPath = process.argv[1] || (await import('node:url')).fileURLToPath(import.meta.url);
         const child = spawn(process.argv[0], [cliPath, '_summarize-file', filePath, hashPrefix, rel], {
@@ -1688,13 +1708,17 @@ const STITCH_SESSION_START_HOOK = {
     matcher: '*',
     hooks: [{ type: 'command', command: 'stitch _hook SessionStart' }],
 };
-// File summary cache: only fires for the Read tool, both pre and post.
+// File summary cache:
+//   • PreToolUse fires only on Read (cached summary surfaces before the read).
+//   • PostToolUse fires on Read, Edit, Write, MultiEdit — Edit/Write/MultiEdit
+//     invalidate any prior summary so a stale "old version" memory never
+//     lingers. The matcher is a regex (Claude Code accepts pipe alternation).
 const STITCH_PRE_READ_HOOK = {
     matcher: 'Read',
     hooks: [{ type: 'command', command: 'stitch _hook' }],
 };
 const STITCH_POST_READ_HOOK = {
-    matcher: 'Read',
+    matcher: 'Read|Edit|Write|MultiEdit',
     hooks: [{ type: 'command', command: 'stitch _hook' }],
 };
 function mergeHook(existing, entry) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stitchdb/cli",
-  "version": "0.7.3",
+  "version": "0.7.4",
   "description": "Stitch CLI — manage memory + run agents from your terminal",
   "type": "module",
   "bin": {