@stitchdb/cli 0.6.0 → 0.7.0

package/dist/cli.js

@@ -420,6 +420,12 @@ async function cmdHook(args) {
     const cfg = loadConfig();
     if (!cfg.apiKey)
         return; // not logged in, silently skip
+    // When the Stitch CLI spawns its own `claude -p` (e.g. for distillation
+    // or file summary extraction), we don't want THAT inner conversation
+    // logged or its tool calls cached — it would create runaway recursion
+    // and pollute the thread with internal prompts.
+    if (process.env.STITCH_HOOKS_DISABLED === '1')
+        return;
     let raw = '';
     try {
         raw = await readStdinAll();
@@ -441,6 +447,16 @@ async function cmdHook(args) {
     // (which is the directory `claude` was launched from).
     const cwd = event?.cwd || process.cwd();
     const threadName = inferThreadFor(cwd) || 'default';
+    // ── PreToolUse on Read: inject cached summary if hash matches ─────────
+    if (eventName === 'PreToolUse' && event?.tool_name === 'Read') {
+        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(() => { });
+        return;
+    }
     // ── SessionStart: inject prior context (token-efficient) ─────────────
     // Strategy: prefer distilled memories (dense facts) over raw turns. Only
     // include raw turns for the last 5 to give the agent immediate continuation.
@@ -448,16 +464,30 @@ async function cmdHook(args) {
         try {
             const stitch = client(cfg);
             const projectTag = (threadName.split('/')[0] || threadName).toLowerCase();
-            const [thread, memHits] = await Promise.all([
+            const [thread, memHits, workspaces, fileSummaries, aboutMems] = await Promise.all([
                 stitch.thread(threadName).recall({ last: 5 }).catch(() => ({ thread_id: '', recent: [], semantic: [] })),
                 stitch.recall(projectTag, { k: 8 }).catch(() => []),
+                stitch.workspaces.list().catch(() => []),
+                stitch.list({ limit: 12 }).then((all) => all.filter((m) => m.tags.some((t) => t.startsWith('file:')))).catch(() => []),
+                stitch.list({ tag: 'workspace:about', limit: 1 }).catch(() => []),
             ]);
+            const currentWs = Array.isArray(workspaces) && workspaces.length > 0 ? workspaces[0] : null;
             const lines = [];
             lines.push('<stitch-context>');
-            lines.push(`Project: ${threadName} · Stitch MCP server is available with tools: recall, remember, thread_recall, thread_append.`);
+            lines.push(`Project: ${threadName} · Workspace: ${currentWs?.name || '(unknown)'} · Stitch MCP tools: recall, remember, thread_recall, thread_append, workspace_setup, file_summary, file_summary_save.`);
             lines.push('');
+            // Nudge the AI to set a meaningful workspace name once.
+            if (currentWs?.name === 'default') {
+                lines.push('### ⚠ Workspace is still named "default"');
+                lines.push('Call the `workspace_setup` MCP tool with a slug-style name based on this project (e.g. the package.json name or repo dir).');
+                lines.push('');
+            }
+            if (Array.isArray(aboutMems) && aboutMems.length > 0) {
+                lines.push('### About this workspace');
+                lines.push(String(aboutMems[0].content || '').slice(0, 400));
+                lines.push('');
+            }
             if (Array.isArray(memHits) && memHits.length > 0) {
-                // Prefer distilled (auto-tagged) facts and decisions; fall back to anything else
                 const sortedMems = [...memHits].sort((a, b) => Number(b.score ?? 0) - Number(a.score ?? 0)).slice(0, 8);
                 lines.push('### Durable memories for this project');
                 for (const m of sortedMems) {
@@ -467,6 +497,16 @@ async function cmdHook(args) {
                 }
                 lines.push('');
             }
+            if (Array.isArray(fileSummaries) && fileSummaries.length > 0) {
+                lines.push('### File summaries (cached — call `file_summary` before reading)');
+                for (const m of fileSummaries.slice(0, 8)) {
+                    const fileTag = m.tags.find((t) => t.startsWith('file:'));
+                    const filePath = fileTag ? fileTag.slice(5) : '(unknown)';
+                    const txt = String(m.content || '').replace(/\n+/g, ' ').slice(0, 250);
+                    lines.push(`- **${filePath}** — ${txt}`);
+                }
+                lines.push('');
+            }
             if (thread.recent && thread.recent.length > 0) {
                 lines.push('### Most recent turns (continue from here)');
                 for (const t of thread.recent.slice(-5)) {
@@ -475,7 +515,7 @@ async function cmdHook(args) {
                 }
                 lines.push('');
             }
-            lines.push('Call `recall` for deeper search or `thread_recall` for older turns when needed.');
+            lines.push('Call `recall` for deeper search, `thread_recall` for older turns, `file_summary` BEFORE reading any non-trivial file (saves tokens).');
             lines.push('</stitch-context>');
             process.stdout.write(lines.join('\n'));
         }
@@ -544,6 +584,38 @@ function inferThreadFor(cwd) {
     }
     return path.basename(dir) || 'default';
 }
+/**
+ * Best-effort derive a workspace slug from a project directory:
+ * - package.json `name` (npm convention, slug-friendly already)
+ * - else folder basename, normalised to a lowercase slug
+ *
+ * The AI can later refine via the `workspace_setup` MCP tool — this is just
+ * the seed name so it isn't "default".
+ */
+function deriveWorkspaceName(cwd) {
+    // 1. package.json `name`.
+    try {
+        const pkgPath = path.join(cwd, 'package.json');
+        if (fs.existsSync(pkgPath)) {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+            if (typeof pkg.name === 'string' && pkg.name.trim()) {
+                // Strip leading scope (@org/) if any — keeps the slug clean.
+                const stripped = pkg.name.replace(/^@[^/]+\//, '').trim();
+                if (stripped)
+                    return slugify(stripped).slice(0, 60);
+            }
+        }
+    }
+    catch { /* fall through */ }
+    // 2. Folder basename.
+    return slugify(path.basename(cwd) || 'default').slice(0, 60) || 'default';
+}
+function slugify(s) {
+    return s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '') || 'default';
+}
 function findProjectRoot(cwd) {
     let cur = cwd;
     for (let i = 0; i < 8; i++) {
@@ -599,6 +671,223 @@ function lastAssistantTextFromTranscript(transcriptPath) {
     catch { /* ignore */ }
     return text;
 }
+// ─── File summary cache ────────────────────────────────────────────────────
+//
+// Goal: when Claude reads a non-trivial file we've seen before, surface our
+// cached 2-3 sentence summary so the agent can decide whether to skim or
+// re-read in full. When Claude reads a file we haven't summarized (or that's
+// changed), kick off a background `claude -p` to extract a summary and save
+// it as a memory tagged `file:<path>` + `hash:<sha-prefix>`.
+//
+// Trade-off: the cache is hash-bound, so any byte change invalidates the
+// cached summary — fine for big stable files (docs, configs, third-party src),
+// less useful for files Claude is actively editing. The PostToolUse hook
+// re-summarizes after the next read, so the cache repopulates on its own.
+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.
+
+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.
+
+Skip preamble. Skip "this file …". Be specific. No markdown fences. No prose around it.
+
+File path: {{PATH}}
+
+File content:
+{{CONTENT}}
+`;
+function readFileContentFromHookEvent(event) {
+    // Claude Code hook 'tool_response' shape varies between versions; accept
+    // a few shapes. The Read tool's success path includes the file content
+    // somewhere in tool_response.
+    const r = event?.tool_response;
+    if (!r)
+        return '';
+    if (typeof r === 'string')
+        return r;
+    if (typeof r?.file?.content === 'string')
+        return r.file.content;
+    if (typeof r?.content === 'string')
+        return r.content;
+    if (Array.isArray(r?.content)) {
+        return r.content.map((c) => (typeof c === 'string' ? c : c?.text ?? '')).join('');
+    }
+    return '';
+}
+function relPathFor(cwd, abs) {
+    try {
+        return path.relative(cwd, abs) || abs;
+    }
+    catch {
+        return abs;
+    }
+}
+async function sha256Hex(s) {
+    const buf = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(s));
+    return [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+async function lookupFileSummary(stitch, relPath) {
+    try {
+        const list = await stitch.list({ tag: `file:${relPath}`, limit: 5 });
+        if (!list || list.length === 0)
+            return null;
+        const first = list[0];
+        const hashTag = first.tags.find((t) => t.startsWith('hash:'));
+        return {
+            id: first.id,
+            content: first.content,
+            hash: hashTag ? hashTag.slice(5) : null,
+            created_at: first.created_at,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// PreToolUse on Read: if we have a cached summary for this exact file path,
+// emit Claude-Code-flavoured JSON to stdout that adds it as additional context.
+async function handlePreReadHook(cfg, event, cwd) {
+    const filePath = String(event?.tool_input?.file_path || '');
+    if (!filePath)
+        return;
+    const rel = relPathFor(cwd, filePath);
+    const stitch = client(cfg);
+    const cached = await lookupFileSummary(stitch, rel);
+    if (!cached)
+        return;
+    const ageMin = Math.round((Date.now() - cached.created_at) / 60_000);
+    const note = [
+        `Stitch cache: a prior summary of ${rel} exists (${ageMin}m ago).`,
+        cached.hash ? `Cached hash prefix: ${cached.hash}.` : '',
+        `Summary: ${cached.content}`,
+        `If the file hasn't changed, you can act on this summary alone and skip a full read; otherwise the read will re-cache the summary.`,
+    ].filter(Boolean).join('\n');
+    // Claude Code accepts a JSON object on stdout for PreToolUse with
+    // hookSpecificOutput.additionalContext to inject text into the model's
+    // context for this tool call.
+    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) {
+    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;
+        }
+    }
+    if (!body || 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];
+    if (last && last.hash === hashPrefix && Date.now() - last.lastSummarizedAt < FILE_SUMMARY_COOLDOWN_MS)
+        return;
+    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.
+    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], {
+            detached: true,
+            stdio: 'ignore',
+            env: { ...process.env, STITCH_HOOKS_DISABLED: '1' },
+        });
+        child.unref();
+    }
+    catch { /* ignore */ }
+}
+// File summary state: per-file cooldown so we don't re-fire on every Read.
+const FILE_SUMMARY_STATE_FILE = path.join(CONFIG_DIR, 'file-summary-state.json');
+function loadFileSummaryState() {
+    try {
+        return JSON.parse(fs.readFileSync(FILE_SUMMARY_STATE_FILE, 'utf8'));
+    }
+    catch {
+        return { files: {} };
+    }
+}
+function saveFileSummaryState(s) {
+    if (!fs.existsSync(CONFIG_DIR))
+        fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(FILE_SUMMARY_STATE_FILE, JSON.stringify(s, null, 2));
+}
+// `stitch _summarize-file <abs> <hashPrefix> <rel>` — internal entry called
+// from the detached PostToolUse spawn. Reads the file, asks claude -p for a
+// 2-3 sentence summary, saves as a Stitch memory.
+async function cmdSummarizeFile(args) {
+    const [abs, hashPrefix, rel] = args;
+    if (!abs || !hashPrefix || !rel)
+        return;
+    const cfg = loadConfig();
+    if (!cfg.apiKey)
+        return;
+    let body = '';
+    try {
+        body = fs.readFileSync(abs, 'utf8');
+    }
+    catch {
+        return;
+    }
+    if (!body || body.length > FILE_SUMMARY_MAX_BYTES)
+        return;
+    const claudeBin = process.env.STITCH_CLAUDE_BIN || 'claude';
+    const prompt = FILE_SUMMARY_PROMPT
+        .replace('{{PATH}}', rel)
+        .replace('{{CONTENT}}', body);
+    const result = await runWithStdin(claudeBin, ['-p'], prompt, {
+        cwd: process.cwd(),
+        env: { STITCH_HOOKS_DISABLED: '1' },
+    });
+    if (result.exit_code !== 0)
+        return;
+    const summary = result.stdout.trim().slice(0, 2000);
+    if (!summary)
+        return;
+    try {
+        const stitch = client(cfg);
+        const projectTag = (inferThread() || 'default').split('/')[0];
+        // Replace any prior summary for this path.
+        const prior = await stitch.list({ tag: `file:${rel}`, limit: 50 }).catch(() => []);
+        for (const p of prior) {
+            try {
+                await stitch.forget(p.id);
+            }
+            catch { }
+        }
+        await stitch.remember(summary, {
+            kind: 'snippet',
+            tags: [`file:${rel}`, `hash:${hashPrefix}`, 'auto:file-summary', `project:${projectTag}`],
+        });
+    }
+    catch { /* silent — never break a session */ }
+}
 // ── stitch link — pin a project's thread name so it's the same on every machine
 async function cmdLink(args) {
     const positionals = positional(args);
@@ -646,29 +935,24 @@ function saveDistillState(s) {
         fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
     fs.writeFileSync(DISTILL_STATE_FILE, JSON.stringify(s, null, 2));
 }
-const DISTILL_PROMPT = `You are a memory distiller for an AI coding assistant.
+const DISTILL_PROMPT = `You are a memory distiller. Output ONLY a JSON array of memory objects. Be GENEROUS — capture every concrete fact about the project that future sessions will care about. Aim for 10–30 memories on a substantial conversation.
 
-Read the conversation below (between a developer and an AI). Extract ONLY
-durable, project-specific facts the developer explicitly stated or decisions
-they explicitly made. Do not invent. Do not extrapolate from implications.
-Skip anything that's tentative, exploratory, or not directly stated.
+Each memory is one atomic, self-contained statement (1–4 sentences) that someone reading it months later — without the conversation around it — will fully understand.
 
-Output a JSON array. Each entry:
-  {
-    "kind": "fact" | "decision" | "snippet" | "preference",
-    "content": "<self-contained, single-paragraph statement>",
-    "tags": ["<short-keyword>", ...]
-  }
+Format:
+  [{"kind":"fact|decision|snippet|preference","content":"...","tags":["short","keywords"]}, ...]
 
-Rules:
-- "fact"        : stable knowledge about this project (architecture, services, schema)
-- "decision"    : explicit choice with rationale (e.g. "we use X because Y")
-- "snippet"     : a reusable code/config/command pattern the user wants kept
-- "preference"  : how the developer wants the AI to behave on this project
-- Each entry must stand alone — readable months later without context.
-- Tags should be 1–3 short keywords.
-- If nothing durable was said, output exactly: []
-- Output ONLY the JSON array. No prose, no code fences, no commentary.
+Capture:
+- fact        — anything concrete: file paths, endpoint URLs, commands, version
+                numbers, architecture, deployed services, schemas, dependencies,
+                bugs found, fixes shipped.
+- decision    — choices with rationale.
+- snippet     — reusable commands/config/code/CLI flags/env var names.
+- preference  — how the developer wants the AI to behave on this project.
+
+Skip pleasantries and questions still being explored. One atomic idea per
+memory — don't bundle. If truly nothing durable was discussed, output: [].
+Output the JSON array and nothing else — no prose, no markdown fences.
 
 Conversation:
 `;
@@ -701,7 +985,29 @@ async function cmdDistill(args) {
     }
     const claudeBin = process.env.STITCH_CLAUDE_BIN || 'claude';
     process.stdout.write(`  → asking ${claudeBin} -p to extract facts… `);
-    const result = await run(claudeBin, ['-p', DISTILL_PROMPT + conversation], { cwd: process.cwd() });
+    const fullPrompt = DISTILL_PROMPT + conversation;
+    // Pipe the prompt via stdin: long conversations blow past ARG_MAX when
+    // passed as `-p <prompt>`, and stdin avoids claude interpreting any
+    // prompt-internal characters as flags. `claude -p` with no value reads
+    // from stdin. STITCH_HOOKS_DISABLED stops our own _hook command from
+    // logging this nested distill conversation as project thread turns.
+    const result = await runWithStdin(claudeBin, ['-p'], fullPrompt, {
+        cwd: process.cwd(),
+        env: { STITCH_HOOKS_DISABLED: '1' },
+    });
+    // Debug capture: STITCH_DEBUG_DISTILL=1 writes raw stdout/stderr/prompt
+    // to /tmp so we can see exactly what claude actually returned.
+    if (process.env.STITCH_DEBUG_DISTILL === '1') {
+        const ts = Date.now();
+        const dbgDir = '/tmp';
+        try {
+            fs.writeFileSync(path.join(dbgDir, `stitch-distill-${ts}.prompt.txt`), fullPrompt);
+            fs.writeFileSync(path.join(dbgDir, `stitch-distill-${ts}.stdout.txt`), result.stdout);
+            fs.writeFileSync(path.join(dbgDir, `stitch-distill-${ts}.stderr.txt`), result.stderr);
+            console.log(`\n  [debug] wrote /tmp/stitch-distill-${ts}.{prompt,stdout,stderr}.txt`);
+        }
+        catch { /* ignore */ }
+    }
     if (result.exit_code !== 0) {
         console.log('failed');
         console.error(result.stderr.trim().slice(0, 400));
@@ -710,6 +1016,10 @@ async function cmdDistill(args) {
     const memories = parseDistillationOutput(result.stdout);
     console.log(`extracted ${memories.length} memories`);
     if (memories.length === 0) {
+        if (process.env.STITCH_DEBUG_DISTILL === '1') {
+            console.error('  [debug] claude stdout (first 600 chars):');
+            console.error('  ' + result.stdout.slice(0, 600).replace(/\n/g, '\n  '));
+        }
         bumpDistillCooldown(thread);
         return;
     }
@@ -739,25 +1049,76 @@ function bumpDistillCooldown(thread) {
     saveDistillState(state);
 }
 function parseDistillationOutput(stdout) {
-    // claude -p sometimes wraps in markdown fences or adds a "Here are the memories:" preamble.
-    // Strip everything outside the first balanced [..] array.
+    // claude -p often wraps the array in markdown fences, prepends prose like
+    // "Here are the extracted memories:", or follows it with a sign-off line.
+    // Strategy: try several extraction modes from most-precise to most-lenient,
+    // returning the first one that parses to a non-empty valid array.
     const text = stdout.trim();
-    const start = text.indexOf('[');
-    const end = text.lastIndexOf(']');
-    if (start === -1 || end === -1 || end < start)
+    if (!text)
         return [];
-    const json = text.slice(start, end + 1);
-    try {
-        const parsed = JSON.parse(json);
-        if (!Array.isArray(parsed))
-            return [];
-        return parsed.filter((m) => m && typeof m === 'object'
-            && typeof m.content === 'string' && m.content.length > 0
-            && typeof m.kind === 'string' && ['fact', 'decision', 'snippet', 'preference', 'note'].includes(m.kind));
+    const candidates = [];
+    // 1. Fenced ```json block
+    const fenced = text.match(/```(?:json)?\s*\n([\s\S]*?)\n```/i);
+    if (fenced)
+        candidates.push(fenced[1].trim());
+    // 2. The first `[ {` … last `} ]` window (skips prose-level stray brackets).
+    const objStart = text.indexOf('[');
+    const objEnd = text.lastIndexOf(']');
+    if (objStart !== -1 && objEnd > objStart) {
+        candidates.push(text.slice(objStart, objEnd + 1));
+    }
+    // 3. Largest `[\n{ ... }\n]` block via balanced scan from each `[`
+    for (let i = 0; i < text.length; i++) {
+        if (text[i] !== '[')
+            continue;
+        let depth = 0;
+        let inStr = false;
+        let esc = false;
+        for (let j = i; j < text.length; j++) {
+            const ch = text[j];
+            if (esc) {
+                esc = false;
+                continue;
+            }
+            if (ch === '\\' && inStr) {
+                esc = true;
+                continue;
+            }
+            if (ch === '"') {
+                inStr = !inStr;
+                continue;
+            }
+            if (inStr)
+                continue;
+            if (ch === '[')
+                depth++;
+            else if (ch === ']') {
+                depth--;
+                if (depth === 0) {
+                    candidates.push(text.slice(i, j + 1));
+                    break;
+                }
+            }
+        }
     }
-    catch {
-        return [];
+    const seen = new Set();
+    for (const cand of candidates) {
+        if (seen.has(cand))
+            continue;
+        seen.add(cand);
+        try {
+            const parsed = JSON.parse(cand);
+            if (!Array.isArray(parsed))
+                continue;
+            const valid = parsed.filter((m) => m && typeof m === 'object'
+                && typeof m.content === 'string' && m.content.length > 0
+                && typeof m.kind === 'string' && ['fact', 'decision', 'snippet', 'preference', 'note'].includes(m.kind));
+            if (valid.length > 0)
+                return valid;
+        }
+        catch { /* try next candidate */ }
     }
+    return [];
 }
 async function distillReview(args) {
     const cfg = loadConfig();
@@ -1102,6 +1463,26 @@ async function cmdInstall(args) {
     const ws = await stitch.resolveWorkspace();
     const baseUrl = cfg.baseUrl || 'https://db.stitchdb.com';
     const mcpUrl = `${baseUrl}/mcp/v1/${ws}`;
+    // 0. If the workspace is still called "default", upgrade its name to a
+    //    project-derived slug so memories surface under a meaningful identity.
+    //    The AI can later refine it via the workspace_setup MCP tool.
+    if (!hasFlag(args, ['--no-rename-workspace'])) {
+        try {
+            const current = await stitch.workspaces.get(ws);
+            if (current.name === 'default') {
+                const derived = deriveWorkspaceName(process.cwd());
+                if (derived && derived !== 'default') {
+                    process.stdout.write(`• Naming workspace "${derived}" (was "default")… `);
+                    await stitch.workspaces.update(ws, { name: derived });
+                    console.log('ok');
+                }
+            }
+        }
+        catch (e) {
+            // Older deployments may not have the PATCH endpoint yet.
+            console.log(`• Workspace rename skipped (${e?.message || e}).`);
+        }
+    }
     const noMcp = hasFlag(args, ['--no-mcp']);
     const noHooks = hasFlag(args, ['--no-hooks']);
     const noClaudeMd = hasFlag(args, ['--no-claude-md']);
@@ -1120,9 +1501,10 @@ async function cmdInstall(args) {
         else
             console.log(`failed (${stderr.trim().slice(0, 120)})`);
     }
-    // 2. Hooks: auto-log every turn + auto-inject prior context at session start
+    // 2. Hooks: auto-log every turn + auto-inject prior context at session start +
+    //          file-summary cache (Pre/PostToolUse on Read).
     if (!noHooks) {
-        process.stdout.write('• Wiring hooks (SessionStart + UserPromptSubmit + Stop)… ');
+        process.stdout.write('• Wiring hooks (SessionStart + UserPromptSubmit + Stop + Pre/PostToolUse:Read)… ');
         try {
             const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
             const existing = fs.existsSync(settingsPath)
@@ -1132,6 +1514,8 @@ async function cmdInstall(args) {
             existing.hooks.SessionStart = mergeHook(existing.hooks.SessionStart, STITCH_SESSION_START_HOOK);
             existing.hooks.UserPromptSubmit = mergeHook(existing.hooks.UserPromptSubmit, STITCH_USER_HOOK);
             existing.hooks.Stop = mergeHook(existing.hooks.Stop, STITCH_STOP_HOOK);
+            existing.hooks.PreToolUse = mergeHook(existing.hooks.PreToolUse, STITCH_PRE_READ_HOOK);
+            existing.hooks.PostToolUse = mergeHook(existing.hooks.PostToolUse, STITCH_POST_READ_HOOK);
             fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
             fs.writeFileSync(settingsPath, JSON.stringify(existing, null, 2));
             console.log('ok');
@@ -1213,10 +1597,11 @@ async function cmdInstall(args) {
     }
     console.log();
     console.log('Done. Open a fresh `claude` session — Stitch is wired.');
-    console.log('  • remember/recall tools are available');
+    console.log('  • workspace_setup, recall, remember, thread tools are available');
     console.log('  • every turn auto-logs to the thread for this repo');
     console.log('  • Claude auto-pulls past context at session start (per CLAUDE.md)');
     console.log('  • Claude memory files are mirrored to Stitch');
+    console.log('  • file Reads auto-cache 2-3 sentence summaries; Pre-Read injects them');
     console.log();
     console.log('Run `stitch sync --watch` to keep them in sync as Claude updates them.');
 }
@@ -1236,6 +1621,15 @@ 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.
+const STITCH_PRE_READ_HOOK = {
+    matcher: 'Read',
+    hooks: [{ type: 'command', command: 'stitch _hook' }],
+};
+const STITCH_POST_READ_HOOK = {
+    matcher: 'Read',
+    hooks: [{ type: 'command', command: 'stitch _hook' }],
+};
 function mergeHook(existing, entry) {
     const arr = Array.isArray(existing) ? existing.slice() : [];
     // Replace any earlier Stitch entry; identify by the marker.
@@ -1387,6 +1781,22 @@ function run(cmd, args, opts = {}) {
         child.on('close', (code) => resolve({ stdout, stderr, exit_code: code ?? 0 }));
     });
 }
+function runWithStdin(cmd, args, stdinData, opts = {}) {
+    return new Promise((resolve) => {
+        const child = spawn(cmd, args, {
+            cwd: opts.cwd || process.cwd(),
+            env: { ...process.env, ...(opts.env || {}) },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (d) => stdout += d.toString());
+        child.stderr.on('data', (d) => stderr += d.toString());
+        child.on('error', (err) => resolve({ stdout, stderr: stderr + '\n[spawn error] ' + err.message, exit_code: 127 }));
+        child.on('close', (code) => resolve({ stdout, stderr, exit_code: code ?? 0 }));
+        child.stdin.end(stdinData);
+    });
+}
 function readLine() {
     return new Promise((resolve) => {
         const onData = (d) => { process.stdin.off('data', onData); resolve(d.toString().trim()); };
@@ -1477,6 +1887,7 @@ async function main(argv) {
             case 'link': return cmdLink(rest);
             case 'distill': return cmdDistill(rest);
             case '_hook': return cmdHook(rest);
+            case '_summarize-file': return cmdSummarizeFile(rest);
             case 'update':
             case 'upgrade': return cmdUpdate(rest);
             case 'version':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stitchdb/cli",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Stitch CLI — manage memory + run agents from your terminal",
   "type": "module",
   "bin": {
@@ -16,7 +16,7 @@
   "license": "MIT",
   "engines": { "node": ">=20" },
   "dependencies": {
-    "@stitchdb/agent": "^0.1.1"
+    "@stitchdb/agent": "^0.2.0"
   },
   "devDependencies": {
     "typescript": "^5.4.0",