@holt-os/holt 0.12.1 → 0.13.0

package/README.md

@@ -71,14 +71,27 @@ Inside `holt chat`:
 /memory           memory stats. /memory <query> previews what recall would surface
 /output           show or set the save format: markdown | html
 /save [name]      save the last reply to a file in this folder
+/allow <path>     let this session read a folder outside this one (session-only)
+/allowed          list folders granted outside-access this session
 /setting          configure brains, API brains, and your launch command
 /clear            forget this session (saved memory stays)
 /help             show commands
 /exit             leave
 ```
 
+A line that starts with `/` is treated as a command only when its first word is a real command. So a message like `/Users/me/resume.docx summarize this` (or a URL, or any sentence that opens with a slash) is sent to the brain as-is, never dropped as an "unknown command".
+
 The point of `/brain`: Holt owns the transcript, so you can start a thread on one model and hand it to another mid-conversation. The new brain picks up with the full context.
 
+### Reading files outside this folder
+
+Holt runs the brain in the folder you launched it from, so by default the brain only sees this folder. If a message references an absolute path (`/...` or `~/...`) that exists **outside** the folder, Holt asks first: `Allow this session to access <dir> (outside this folder)? [y/N]`. Answer `y` and it grants the file's **containing directory** read access for the rest of this chat. Answer `n` and the message still goes through, the brain just does not get that folder.
+
+- `/allow <path>` grants a folder up front with no prompt.
+- `/allowed` lists what you have granted.
+
+Grants are **in-memory and session-scoped**: nothing is written to disk, and they reset the next time you run `holt chat`. Access is **read-oriented** and only works with a **Claude Code** brain: Holt passes `--add-dir=<dir>` for each granted folder plus `--allowedTools=Read,Glob,Grep` so Claude Code can read (but not write) those files without an interactive permission prompt. With a Codex/Gemini or API brain, external file access is unavailable and Holt says so instead of adding flags. (If you need to tune the flags, they live in one place: `claudeAccessArgs` in `src/access.ts`.)
+
 ## Memory
 
 Every exchange is saved to `<folder>/.holt/memory/turns.jsonl`, private and local. On each message, Holt recalls the most relevant moments from your *past* sessions in that folder and hands them to the brain, so it remembers what you told it last week.

package/dist/cli.js

@@ -105,11 +105,11 @@ function createReader() {
     closed = true;
     while (waiters.length) waiters.shift()(null);
   });
-  const ask = (q) => new Promise((resolve8) => {
+  const ask = (q) => new Promise((resolve9) => {
     if (q) process.stdout.write(q);
-    if (buffer.length) resolve8(buffer.shift());
-    else if (closed) resolve8(null);
-    else waiters.push(resolve8);
+    if (buffer.length) resolve9(buffer.shift());
+    else if (closed) resolve9(null);
+    else waiters.push(resolve9);
   });
   return { ask, close: () => rl.close() };
 }
@@ -307,13 +307,13 @@ function renderPrompt(history, message, memory = []) {
   parts.push("", `User: ${message}`, "", "Assistant:");
   return parts.join("\n");
 }
-function runBrain(brain, prompt, onChunk) {
-  return new Promise((resolve8) => {
+function runBrain(brain, prompt, onChunk, extraArgs = []) {
+  return new Promise((resolve9) => {
     let child;
     try {
-      child = spawn(brain.command, [...brain.args, prompt], { stdio: ["ignore", "pipe", "pipe"] });
+      child = spawn(brain.command, [...brain.args, ...extraArgs, prompt], { stdio: ["ignore", "pipe", "pipe"] });
     } catch (e) {
-      resolve8({ ok: false, text: `Could not launch "${brain.command}": ${e.message}` });
+      resolve9({ ok: false, text: `Could not launch "${brain.command}": ${e.message}` });
       return;
     }
     let out = "";
@@ -326,11 +326,11 @@ function runBrain(brain, prompt, onChunk) {
     child.stderr.on("data", (d) => {
       err2 += d.toString();
     });
-    child.on("error", (e) => resolve8({ ok: false, text: `Could not run "${brain.command}": ${e.message}` }));
+    child.on("error", (e) => resolve9({ ok: false, text: `Could not run "${brain.command}": ${e.message}` }));
     child.on("close", (code) => {
       const text = out.trim();
-      if (code === 0 && text) resolve8({ ok: true, text });
-      else resolve8({ ok: false, text: err2.trim() || text || `"${brain.command}" exited with code ${code}` });
+      if (code === 0 && text) resolve9({ ok: true, text });
+      else resolve9({ ok: false, text: err2.trim() || text || `"${brain.command}" exited with code ${code}` });
     });
   });
 }
@@ -500,16 +500,16 @@ function currentAlias() {
 // src/install.ts
 import { spawn as spawn2 } from "child_process";
 function runInteractive(cmd, args) {
-  return new Promise((resolve8) => {
+  return new Promise((resolve9) => {
     let child;
     try {
       child = spawn2(cmd, args, { stdio: "inherit" });
     } catch {
-      resolve8(-1);
+      resolve9(-1);
       return;
     }
-    child.on("error", () => resolve8(-1));
-    child.on("close", (code) => resolve8(code ?? -1));
+    child.on("error", () => resolve9(-1));
+    child.on("close", (code) => resolve9(code ?? -1));
   });
 }
 
@@ -2982,6 +2982,77 @@ function saveReply(reply, format, name) {
   return path;
 }
 
+// src/access.ts
+import { existsSync as existsSync9, realpathSync as realpathSync2, statSync as statSync4 } from "fs";
+import { homedir as homedir3 } from "os";
+import { dirname as dirname3, isAbsolute as isAbsolute2, resolve as resolve2, sep } from "path";
+function expandHome(p) {
+  if (p === "~") return homedir3();
+  if (p.startsWith("~/")) return resolve2(homedir3(), p.slice(2));
+  return p;
+}
+function isInside(child, parent) {
+  if (child === parent) return true;
+  const base = parent.endsWith(sep) ? parent : parent + sep;
+  return child.startsWith(base);
+}
+function resolveExisting(token) {
+  const expanded = expandHome(token);
+  const abs = isAbsolute2(expanded) ? expanded : resolve2(process.cwd(), expanded);
+  if (!existsSync9(abs)) return null;
+  try {
+    return realpathSync2(abs);
+  } catch {
+    return abs;
+  }
+}
+function containingDir(absPath) {
+  try {
+    return statSync4(absPath).isDirectory() ? absPath : dirname3(absPath);
+  } catch {
+    return dirname3(absPath);
+  }
+}
+function resolveGrantDir(token) {
+  const expanded = expandHome(token);
+  const abs = isAbsolute2(expanded) ? expanded : resolve2(process.cwd(), expanded);
+  let real = abs;
+  try {
+    real = realpathSync2(abs);
+  } catch {
+  }
+  return containingDir(real);
+}
+function findOutsidePaths(message, workspaceDir) {
+  const ws = (() => {
+    try {
+      return realpathSync2(workspaceDir);
+    } catch {
+      return resolve2(workspaceDir);
+    }
+  })();
+  const holt = wsHoltDir(ws);
+  const tokens2 = message.match(/(?:~\/|\/|~(?=\s|$))[^\s]*/g) ?? [];
+  const dirs = /* @__PURE__ */ new Set();
+  for (const rawToken of tokens2) {
+    const token = rawToken.replace(/[.,;:!?)"'\]]+$/, "");
+    if (!token) continue;
+    const abs = resolveExisting(token);
+    if (!abs) continue;
+    if (isInside(abs, ws)) continue;
+    if (isInside(abs, holt)) continue;
+    dirs.add(containingDir(abs));
+  }
+  return [...dirs];
+}
+function claudeAccessArgs(grantedDirs) {
+  const dirs = [...grantedDirs];
+  if (dirs.length === 0) return [];
+  const args = dirs.map((d) => `--add-dir=${d}`);
+  args.push("--allowedTools=Read,Glob,Grep");
+  return args;
+}
+
 // src/commands/chat.ts
 function statusLine(brainLabel, history) {
   const live = Math.min(history.length, MAX_REPLAY_TURNS);
@@ -2989,6 +3060,25 @@ function statusLine(brainLabel, history) {
   const mem = memStats().turns;
   return c.dim("  " + brainLabel + "  ") + c.dim("[") + bar(frac) + c.dim("]") + c.dim(`  recent ${live}/${MAX_REPLAY_TURNS}  \xB7  ${mem} in memory`);
 }
+var KNOWN_COMMANDS = /* @__PURE__ */ new Set([
+  "exit",
+  "quit",
+  "q",
+  "help",
+  "h",
+  "clear",
+  "memory",
+  "mem",
+  "output",
+  "save",
+  "setting",
+  "settings",
+  "brain",
+  "skill",
+  "skills",
+  "allow",
+  "allowed"
+]);
 function help() {
   console.log(c.dim([
     "  commands:",
@@ -2997,6 +3087,8 @@ function help() {
     '    /skill [name] [input]  run a skill, or list them. "holt skill" manages them.',
     "    /output [fmt]     show or set output format: markdown | html",
     "    /save [name]      save the last reply to a file in this folder",
+    "    /allow [path]     let this session read a folder outside this one (session-only)",
+    "    /allowed          list folders granted outside-access this session",
     "    /setting          configure brains, API brains, and your launch command",
     "    /clear            forget this session so far (saved memory stays)",
     "    /help             this list",
@@ -3043,6 +3135,7 @@ async function chat() {
   const session = newSessionId();
   const history = [];
   let lastReply = "";
+  const grantedDirs = /* @__PURE__ */ new Set();
   const sb = createStatusBar();
   const showStatus = () => {
     const line = statusLine(active.label, history);
@@ -3058,7 +3151,7 @@ async function chat() {
   if (embedOk && stats.withEmbeddings < stats.turns) {
     console.log(c.dim(`  ${stats.turns - stats.withEmbeddings} older moments lack embeddings. Run "holt memory embed" to upgrade them.`));
   }
-  console.log(c.dim("Type a message. Commands: /brain  /memory  /output  /save  /setting  /clear  /help  /exit"));
+  console.log(c.dim("Type a message. Commands: /brain  /memory  /output  /save  /allow  /setting  /clear  /help  /exit"));
   showStatus();
   while (true) {
     const raw = await ask(c.accent("\u203A "));
@@ -3074,7 +3167,7 @@ async function chat() {
       }
       promptOverride = inv.prompt;
       console.log(c.dim(`  running skill "${inv.skillName}"...`));
-    } else if (line.startsWith("/")) {
+    } else if (line.startsWith("/") && KNOWN_COMMANDS.has((line.slice(1).split(/\s+/)[0] || "").toLowerCase())) {
       const parts = line.slice(1).split(/\s+/);
       const cmd = (parts[0] || "").toLowerCase();
       const rest = parts.slice(1).join(" ");
@@ -3169,6 +3262,24 @@ async function chat() {
         console.log(c.dim("  skills: " + (names.join("  ") || "none") + "   usage: /skill <name> [input]"));
         continue;
       }
+      if (cmd === "allowed") {
+        if (grantedDirs.size === 0) console.log(c.dim("  no folders outside this one are granted this session."));
+        else {
+          console.log(c.dim("  granted this session (read-only):"));
+          for (const d of grantedDirs) console.log(c.dim(`    ${d}`));
+        }
+        continue;
+      }
+      if (cmd === "allow") {
+        if (!rest) {
+          console.log(c.dim("  usage: /allow <path>   (grants that path's folder read access for this session)"));
+          continue;
+        }
+        const dir = resolveGrantDir(rest);
+        grantedDirs.add(dir);
+        console.log(c.green(`  granted this session: ${dir}`));
+        continue;
+      }
       console.log(c.dim(`  unknown command: /${cmd}  (try /help)`));
       continue;
     }
@@ -3180,18 +3291,39 @@ async function chat() {
       console.log(c.red(`  ${active.label} has no API key. Use /setting to add one, or /brain to switch.`));
       continue;
     }
+    if (promptOverride === null) {
+      const outside = findOutsidePaths(line, workspace());
+      for (const dir of outside) {
+        if (grantedDirs.has(dir)) continue;
+        const ans = (await ask(c.dim(`  Allow this session to access ${dir} (outside this folder)? [y/N] `)) ?? "").trim().toLowerCase();
+        if (ans === "y" || ans === "yes") {
+          grantedDirs.add(dir);
+          console.log(c.green(`  granted this session: ${dir}`));
+        } else {
+          console.log(c.dim("  not granted."));
+        }
+      }
+    }
     const remembered = await recall(line, session, 4);
-    const label = remembered.length ? `${active.label} is thinking (recalled ${remembered.length} moment${remembered.length === 1 ? "" : "s"})...` : `${active.label} is thinking...`;
+    const label = remembered.length ? `Holt is thinking (recalled ${remembered.length} moment${remembered.length === 1 ? "" : "s"})...` : `Holt is thinking...`;
     console.log(c.dim(`  ${label}`) + "\n");
     const skillsBlock = skillsPromptBlock();
     const base = renderPrompt(history, line, remembered);
     const prompt = promptOverride ?? (skillsBlock ? skillsBlock + "\n\n" + base : base);
+    let extraArgs = [];
+    if (grantedDirs.size > 0) {
+      if (active.kind === "cli" && cfg.brains[active.id].command === "claude") {
+        extraArgs = claudeAccessArgs(grantedDirs);
+      } else {
+        console.log(c.dim("  note: external file access is only available with a Claude Code brain; skipping granted folders this turn."));
+      }
+    }
     let streamed = false;
     const onChunk = (chunk2) => {
       streamed = true;
       process.stdout.write(chunk2);
     };
-    const res = active.kind === "cli" ? await runBrain(cfg.brains[active.id], prompt, onChunk) : await runApiBrain(active.brain, prompt, onChunk);
+    const res = active.kind === "cli" ? await runBrain(cfg.brains[active.id], prompt, onChunk, extraArgs) : await runApiBrain(active.brain, prompt, onChunk);
     if (res.ok) {
       if (!streamed) console.log(res.text);
       if (!res.text.endsWith("\n")) console.log("");
@@ -3251,7 +3383,7 @@ async function login(which) {
 }
 
 // src/commands/memory.ts
-import { existsSync as existsSync9, readFileSync as readFileSync10 } from "fs";
+import { existsSync as existsSync10, readFileSync as readFileSync10 } from "fs";
 import { basename } from "path";
 async function memoryCmd(sub, rest = []) {
   const { ask, close } = createReader();
@@ -3299,7 +3431,7 @@ async function memoryCmd(sub, rest = []) {
     return;
   }
   if (action === "facts") {
-    if (!existsSync9(factsMdPath())) {
+    if (!existsSync10(factsMdPath())) {
       console.log(c.dim("\n  No facts distilled yet. They form when you end a chat session.\n"));
       close();
       return;
@@ -3418,7 +3550,7 @@ function globalCmd(act, rest) {
 }
 
 // src/commands/wiki.ts
-import { existsSync as existsSync10, readFileSync as readFileSync11 } from "fs";
+import { existsSync as existsSync11, readFileSync as readFileSync11 } from "fs";
 import { join as join10 } from "path";
 import { spawn as spawn3 } from "child_process";
 function titleToSlug(title) {
@@ -3612,7 +3744,7 @@ function listCmd() {
   for (const slug of slugs) {
     const pg = readPage(slug);
     if (!pg) continue;
-    const size = existsSync10(join10(wikiDir(), slug + ".md")) ? (readFileSync11(join10(wikiDir(), slug + ".md"), "utf8").length / 1024).toFixed(1) : "0.0";
+    const size = existsSync11(join10(wikiDir(), slug + ".md")) ? (readFileSync11(join10(wikiDir(), slug + ".md"), "utf8").length / 1024).toFixed(1) : "0.0";
     console.log(`  ${c.cyan(pg.title.padEnd(28).slice(0, 28))} ${c.dim(pg.updated || "          ")}  ${size} KB`);
   }
   console.log("");
@@ -3700,8 +3832,8 @@ function setupCmd(cfg) {
 `));
 }
 function openCmd() {
-  const target = existsSync10(wikiIndexPath()) ? wikiIndexPath() : wikiDir();
-  if (!existsSync10(target)) {
+  const target = existsSync11(wikiIndexPath()) ? wikiIndexPath() : wikiDir();
+  if (!existsSync11(target)) {
     console.log(c.dim('\n  No wiki yet. Run "holt wiki sync" first.\n'));
     return;
   }
@@ -3791,20 +3923,20 @@ import {
   mkdirSync as mkdirSync9,
   writeFileSync as writeFileSync10,
   readFileSync as readFileSync13,
-  existsSync as existsSync12,
+  existsSync as existsSync13,
   readdirSync as readdirSync3,
-  statSync as statSync5,
+  statSync as statSync6,
   rmSync as rmSync5,
   cpSync,
   mkdtempSync
 } from "fs";
-import { join as join12, resolve as resolve3, sep, isAbsolute as isAbsolute3 } from "path";
+import { join as join12, resolve as resolve4, sep as sep2, isAbsolute as isAbsolute4 } from "path";
 import { tmpdir } from "os";
 import { spawnSync as spawnSync2 } from "child_process";
 
 // src/registry.ts
-import { readFileSync as readFileSync12, writeFileSync as writeFileSync9, existsSync as existsSync11, mkdirSync as mkdirSync8, statSync as statSync4 } from "fs";
-import { join as join11, isAbsolute as isAbsolute2, resolve as resolve2 } from "path";
+import { readFileSync as readFileSync12, writeFileSync as writeFileSync9, existsSync as existsSync12, mkdirSync as mkdirSync8, statSync as statSync5 } from "fs";
+import { join as join11, isAbsolute as isAbsolute3, resolve as resolve3 } from "path";
 import { pathToFileURL, fileURLToPath as fileURLToPath2 } from "url";
 var DEFAULT_REGISTRY_URL = "https://raw.githubusercontent.com/holt-os/registry/main/registry.json";
 var REGISTRY_REPO_URL = "https://github.com/holt-os/registry";
@@ -3849,7 +3981,7 @@ function parseRegistry(text) {
 function readCache() {
   try {
     const path = registryCachePath();
-    if (!existsSync11(path)) return null;
+    if (!existsSync12(path)) return null;
     const raw = JSON.parse(readFileSync12(path, "utf8"));
     if (!raw || typeof raw.fetchedAt !== "number" || typeof raw.url !== "string") return null;
     const registry = coerceRegistry(raw.registry);
@@ -3876,12 +4008,12 @@ function localPathFor(loc) {
     }
   }
   if (/^https?:\/\//i.test(loc)) return null;
-  return isAbsolute2(loc) ? loc : resolve2(loc);
+  return isAbsolute3(loc) ? loc : resolve3(loc);
 }
 var UNREACHABLE_MSG = "no registry reachable; set HOLT_REGISTRY_URL or the community registry is not live yet";
 function loadLocal(path) {
   try {
-    if (!existsSync11(path)) {
+    if (!existsSync12(path)) {
       return { registry: null, fromCache: false, error: UNREACHABLE_MSG };
     }
     const registry = parseRegistry(readFileSync12(path, "utf8"));
@@ -4004,21 +4136,21 @@ function splitSubpath(source) {
   return { base: source.slice(0, i), subpath: source.slice(i + 1) };
 }
 function resolveSubpathDir(fetched, subpath) {
-  if (isAbsolute3(subpath)) return null;
+  if (isAbsolute4(subpath)) return null;
   const segments = subpath.split(/[\\/]/);
   if (segments.some((s) => s === "..")) return null;
-  const target = resolve3(fetched, subpath);
-  const root = resolve3(fetched);
-  if (target !== root && !target.startsWith(root + sep)) return null;
+  const target = resolve4(fetched, subpath);
+  const root = resolve4(fetched);
+  if (target !== root && !target.startsWith(root + sep2)) return null;
   return target;
 }
 function findSkillDir(root) {
-  if (existsSync12(join12(root, "SKILL.md"))) return root;
+  if (existsSync13(join12(root, "SKILL.md"))) return root;
   let subs = [];
   try {
     subs = readdirSync3(root).filter((f) => {
       try {
-        return statSync5(join12(root, f)).isDirectory();
+        return statSync6(join12(root, f)).isDirectory();
       } catch {
         return false;
       }
@@ -4026,7 +4158,7 @@ function findSkillDir(root) {
   } catch {
     return null;
   }
-  const withSkill = subs.filter((f) => existsSync12(join12(root, f, "SKILL.md")));
+  const withSkill = subs.filter((f) => existsSync13(join12(root, f, "SKILL.md")));
   if (withSkill.length === 1) return join12(root, withSkill[0]);
   return null;
 }
@@ -4081,7 +4213,7 @@ function cmdCreate(name, global) {
   }
   const scope = global ? "global" : "workspace";
   const dir = join12(skillsRoot(scope), clean);
-  if (existsSync12(dir)) {
+  if (existsSync13(dir)) {
     console.error(c.red(`
   A ${scope} skill named "${clean}" already exists.`));
     console.error(c.dim("  " + dir + "\n"));
@@ -4112,8 +4244,8 @@ function installFromSource(source, scope) {
       }
       fetched = tempDir;
     } else {
-      fetched = resolve3(base);
-      if (!existsSync12(fetched)) {
+      fetched = resolve4(base);
+      if (!existsSync13(fetched)) {
         console.error(c.red(`
   No such path: ${fetched}
 `));
@@ -4131,7 +4263,7 @@ function installFromSource(source, scope) {
         process.exitCode = 1;
         return false;
       }
-      if (!existsSync12(target) || !statSync5(target).isDirectory()) {
+      if (!existsSync13(target) || !statSync6(target).isDirectory()) {
         console.error(c.red(`
   Subpath "${subpath}" does not exist in the source.
 `));
@@ -4163,7 +4295,7 @@ function installFromSource(source, scope) {
       return false;
     }
     const dest = join12(skillsRoot(scope), skillName);
-    if (existsSync12(dest)) {
+    if (existsSync13(dest)) {
       console.error(c.red(`
   A ${scope} skill named "${skillName}" already exists.`));
       console.error(c.dim("  " + dest + "\n"));
@@ -4173,13 +4305,13 @@ function installFromSource(source, scope) {
     mkdirSync9(skillsRoot(scope), { recursive: true });
     cpSync(skillDir, dest, { recursive: true });
     const nestedGit = join12(dest, ".git");
-    if (existsSync12(nestedGit)) rmSync5(nestedGit, { recursive: true, force: true });
+    if (existsSync13(nestedGit)) rmSync5(nestedGit, { recursive: true, force: true });
     console.log(c.green(`
   Installed ${scope} skill "${skillName}".`));
     console.log(c.dim("  " + join12(dest, "SKILL.md") + "\n"));
     return true;
   } finally {
-    if (tempDir && existsSync12(tempDir)) {
+    if (tempDir && existsSync13(tempDir)) {
       try {
         rmSync5(tempDir, { recursive: true, force: true });
       } catch {
@@ -4194,7 +4326,7 @@ async function cmdAdd(source, global, refresh) {
   }
   const scope = global ? "global" : "workspace";
   const { base } = splitSubpath(source);
-  if (isGitUrl(base) || existsSync12(resolve3(base))) {
+  if (isGitUrl(base) || existsSync13(resolve4(base))) {
     installFromSource(source, scope);
     return;
   }
@@ -4277,7 +4409,7 @@ function cmdPublish(name) {
     description = (data.description || loaded.skill.description || "").trim();
   } else {
     const file = join12(process.cwd(), "SKILL.md");
-    if (!existsSync12(file)) {
+    if (!existsSync13(file)) {
       console.error(c.red("\n  No SKILL.md in the current directory, and no skill name given."));
       console.error(c.dim("  Usage: holt skill publish [<name>]\n"));
       process.exitCode = 1;
@@ -4321,9 +4453,9 @@ async function cmdRemove(name, ask) {
   }
   const wsDir = join12(skillsRoot("workspace"), clean);
   const globalDir = join12(skillsRoot("global"), clean);
-  const target = existsSync12(wsDir) ? wsDir : existsSync12(globalDir) ? globalDir : "";
+  const target = existsSync13(wsDir) ? wsDir : existsSync13(globalDir) ? globalDir : "";
   if (!target) {
-    if (existsSync12(join12(skillsRoot("builtin"), clean))) {
+    if (existsSync13(join12(skillsRoot("builtin"), clean))) {
       console.error(c.red(`
   "${clean}" is a built-in skill and cannot be removed; it ships inside Holt.`));
       console.error(c.dim("  Override it instead: create a workspace or global skill with the same name.\n"));
@@ -4396,8 +4528,8 @@ async function skillCmd(sub, rest = []) {
 }
 
 // src/commands/graph.ts
-import { writeFileSync as writeFileSync11, mkdirSync as mkdirSync10, existsSync as existsSync13 } from "fs";
-import { join as join14, dirname as dirname4, resolve as resolve4 } from "path";
+import { writeFileSync as writeFileSync11, mkdirSync as mkdirSync10, existsSync as existsSync14 } from "fs";
+import { join as join14, dirname as dirname5, resolve as resolve5 } from "path";
 import { spawn as spawn4 } from "child_process";
 
 // src/communities.ts
@@ -5194,8 +5326,8 @@ function renderGraphHtml(graph2, meta) {
 }
 
 // src/ingest.ts
-import { readdirSync as readdirSync4, readFileSync as readFileSync14, statSync as statSync6 } from "fs";
-import { join as join13, relative, sep as sep2, extname, dirname as dirname3, basename as basename2 } from "path";
+import { readdirSync as readdirSync4, readFileSync as readFileSync14, statSync as statSync7 } from "fs";
+import { join as join13, relative, sep as sep3, extname, dirname as dirname4, basename as basename2 } from "path";
 var CODE_EXT = /* @__PURE__ */ new Set([
   "js",
   "jsx",
@@ -5246,7 +5378,7 @@ var MAX_FILES = 2e3;
 var MAX_FILE_BYTES = 400 * 1024;
 var MAX_TOTAL_BYTES = 64 * 1024 * 1024;
 function toPosix(p) {
-  return sep2 === "/" ? p : p.split(sep2).join("/");
+  return sep3 === "/" ? p : p.split(sep3).join("/");
 }
 function ingestFolder(root, want = { code: true, docs: true }) {
   const files = [];
@@ -5271,7 +5403,7 @@ function ingestFolder(root, want = { code: true, docs: true }) {
       const full = join13(dir, name);
       let st;
       try {
-        st = statSync6(full);
+        st = statSync7(full);
       } catch {
         skipped.unreadable++;
         continue;
@@ -5435,7 +5567,7 @@ function resolvePySpec(f, spec, byId) {
   return null;
 }
 function toPosixDir(id) {
-  const d = toPosix(dirname3(id));
+  const d = toPosix(dirname4(id));
   return d === "" || d === "." ? "." : d;
 }
 var MD_LINK_RE = /\[[^\]]*\]\(([^)\s]+)(?:\s+["'][^"']*["'])?\)/g;
@@ -5607,7 +5739,7 @@ async function graph(args = []) {
   const ingestCode = opts.code;
   const ingestDocs = opts.docs;
   const turns = loadTurns();
-  const includeWiki = opts.wiki !== void 0 ? opts.wiki : existsSync13(wikiDir());
+  const includeWiki = opts.wiki !== void 0 ? opts.wiki : existsSync14(wikiDir());
   const wikiPages = includeWiki ? wikiGraphPages() : [];
   let fileNodeCount = 0;
   let docNodeCount = 0;
@@ -5637,8 +5769,8 @@ async function graph(args = []) {
   if (codeGraph) assignCommunities(g);
   if (opts.report) {
     const md = renderReport(g, { workspace: workspace() });
-    const reportPath = opts.out ? resolve4(opts.out) : join14(workspace(), "GRAPH_REPORT.md");
-    mkdirSync10(dirname4(reportPath), { recursive: true });
+    const reportPath = opts.out ? resolve5(opts.out) : join14(workspace(), "GRAPH_REPORT.md");
+    mkdirSync10(dirname5(reportPath), { recursive: true });
     writeFileSync11(reportPath, md, "utf8");
     const communities = new Set(g.nodes.map((n) => n.community ?? "0")).size;
     console.log("\n" + c.accent("Graph report written") + c.dim("  (this folder)"));
@@ -5659,8 +5791,8 @@ async function graph(args = []) {
     concepts: conceptCount,
     edges: g.edges.length
   });
-  const outPath = opts.out ? resolve4(opts.out) : join14(wsHoltDir(), "graph.html");
-  mkdirSync10(dirname4(outPath), { recursive: true });
+  const outPath = opts.out ? resolve5(opts.out) : join14(wsHoltDir(), "graph.html");
+  mkdirSync10(dirname5(outPath), { recursive: true });
   writeFileSync11(outPath, html, "utf8");
   console.log("\n" + c.accent("Memory graph built") + c.dim("  (this folder)"));
   const parts = [`${turns.length} turns`, `${conceptCount} concepts`];
@@ -5773,7 +5905,7 @@ function recoverId(line) {
   return null;
 }
 function runMcpServer(opts) {
-  return new Promise((resolve8) => {
+  return new Promise((resolve9) => {
     const stdin = process.stdin;
     let buffer = "";
     let chain = Promise.resolve();
@@ -5825,11 +5957,11 @@ function runMcpServer(opts) {
         processLine(buffer);
         buffer = "";
       }
-      chain.then(() => resolve8()).catch(() => resolve8());
+      chain.then(() => resolve9()).catch(() => resolve9());
     });
     stdin.on("error", (e) => {
       console.error(`[mcp] stdin error: ${e.message}`);
-      chain.then(() => resolve8()).catch(() => resolve8());
+      chain.then(() => resolve9()).catch(() => resolve9());
     });
     stdin.resume();
   });
@@ -5949,7 +6081,7 @@ function holtTools() {
 }
 
 // src/version.ts
-var VERSION = "0.12.1";
+var VERSION = "0.13.0";
 
 // src/commands/mcp.ts
 function printSetup() {
@@ -5995,10 +6127,10 @@ async function mcp(sub, rest = []) {
 }
 
 // src/commands/hook.ts
-import { readFileSync as readFileSync15, writeFileSync as writeFileSync12, existsSync as existsSync14, mkdirSync as mkdirSync11, copyFileSync, realpathSync as realpathSync2, appendFileSync as appendFileSync2, statSync as statSync7 } from "fs";
+import { readFileSync as readFileSync15, writeFileSync as writeFileSync12, existsSync as existsSync15, mkdirSync as mkdirSync11, copyFileSync, realpathSync as realpathSync3, appendFileSync as appendFileSync2, statSync as statSync8 } from "fs";
 import { spawnSync as spawnSync3 } from "child_process";
-import { join as join15, dirname as dirname5 } from "path";
-import { homedir as homedir3 } from "os";
+import { join as join15, dirname as dirname6 } from "path";
+import { homedir as homedir4 } from "os";
 var EVENT = {
   inject: "UserPromptSubmit",
   capture: "Stop"
@@ -6008,13 +6140,13 @@ var HOOK_CMD = {
   capture: "holt hook capture"
 };
 function globalSettingsPath() {
-  return join15(homedir3(), ".claude", "settings.json");
+  return join15(homedir4(), ".claude", "settings.json");
 }
 function projectSettingsPath() {
   return join15(process.cwd(), ".claude", "settings.json");
 }
 function readSettings(path) {
-  if (!existsSync14(path)) return {};
+  if (!existsSync15(path)) return {};
   try {
     const parsed = JSON.parse(readFileSync15(path, "utf8"));
     return parsed && typeof parsed === "object" ? parsed : {};
@@ -6023,11 +6155,11 @@ function readSettings(path) {
   }
 }
 function writeSettings(path, settings) {
-  mkdirSync11(dirname5(path), { recursive: true });
+  mkdirSync11(dirname6(path), { recursive: true });
   writeFileSync12(path, JSON.stringify(settings, null, 2) + "\n", "utf8");
 }
 function backup(path) {
-  if (!existsSync14(path)) return null;
+  if (!existsSync15(path)) return null;
   const dest = `${path}.holt-bak`;
   try {
     copyFileSync(path, dest);
@@ -6117,7 +6249,7 @@ function remove(rest) {
   const paths = project ? [projectSettingsPath()] : [globalSettingsPath(), projectSettingsPath()];
   let touchedAny = false;
   for (const path of paths) {
-    if (!existsSync14(path)) continue;
+    if (!existsSync15(path)) continue;
     let settings;
     try {
       settings = readSettings(path);
@@ -6147,7 +6279,7 @@ function status(rest) {
   ];
   console.log(c.accent("  Holt ambient hooks"));
   for (const e of entries) {
-    if (!existsSync14(e.path)) {
+    if (!existsSync15(e.path)) {
       console.log(c.dim(`  ${e.label.padEnd(8)} ${e.path}  (no settings file)`));
       continue;
     }
@@ -6167,13 +6299,13 @@ function status(rest) {
   console.log(c.dim("  Runtime hooks only act in trusted Holt folders that already have .holt/memory."));
 }
 function readStdin(timeoutMs) {
-  return new Promise((resolve8) => {
+  return new Promise((resolve9) => {
     let input = "";
     let done = false;
     const finish = () => {
       if (done) return;
       done = true;
-      resolve8(input);
+      resolve9(input);
     };
     try {
       process.stdin.setEncoding("utf8");
@@ -6197,9 +6329,9 @@ function parseHookInput(raw) {
   }
 }
 function enterFolder(cwd) {
-  if (!cwd || !existsSync14(cwd)) return null;
+  if (!cwd || !existsSync15(cwd)) return null;
   try {
-    const real = realpathSync2(cwd);
+    const real = realpathSync3(cwd);
     process.chdir(real);
     return real;
   } catch {
@@ -6208,7 +6340,7 @@ function enterFolder(cwd) {
 }
 function guardTrusted(real) {
   if (!isTrusted(real)) return false;
-  if (!existsSync14(memDir())) return false;
+  if (!existsSync15(memDir())) return false;
   return true;
 }
 function hookLog(msg) {
@@ -6222,11 +6354,37 @@ function hookLog(msg) {
 function fileBytes(path) {
   if (!path) return 0;
   try {
-    return statSync7(path).size;
+    return statSync8(path).size;
   } catch {
     return 0;
   }
 }
+var THROTTLE_MIN_NEW_EXCHANGES = 2;
+function hookStatePath() {
+  return join15(GLOBAL_DIR, "hook-state.json");
+}
+function readHookState() {
+  try {
+    const parsed = JSON.parse(readFileSync15(hookStatePath(), "utf8"));
+    if (!parsed || typeof parsed !== "object") return {};
+    return parsed;
+  } catch {
+    return {};
+  }
+}
+function lastProcessedExchanges(state, sessionId) {
+  const rec = state[sessionId];
+  return rec && typeof rec.lastExchanges === "number" ? rec.lastExchanges : 0;
+}
+function saveHookState(sessionId, exchanges) {
+  try {
+    mkdirSync11(GLOBAL_DIR, { recursive: true });
+    const state = readHookState();
+    state[sessionId] = { lastExchanges: exchanges };
+    writeFileSync12(hookStatePath(), JSON.stringify(state, null, 2) + "\n", "utf8");
+  } catch {
+  }
+}
 async function inject() {
   const debug = !!process.env.HOLT_HOOK_DEBUG;
   const dlog = (m) => {
@@ -6325,17 +6483,17 @@ function readTranscript(path) {
   return out;
 }
 function resolveCommandPath(command) {
-  if (command.startsWith("/") && existsSync14(command)) return command;
+  if (command.startsWith("/") && existsSync15(command)) return command;
   try {
     const shell = process.env.SHELL || "/bin/sh";
     const res = spawnSync3(shell, ["-lc", "command -v " + command], { encoding: "utf8" });
     if (res.status === 0) {
       const p = (res.stdout || "").trim().split("\n")[0]?.trim();
-      if (p && p.startsWith("/") && existsSync14(p)) return p;
+      if (p && p.startsWith("/") && existsSync15(p)) return p;
     }
   } catch {
   }
-  const home = homedir3();
+  const home = homedir4();
   const dirs = [
     join15(home, ".local", "bin"),
     "/opt/homebrew/bin",
@@ -6346,7 +6504,7 @@ function resolveCommandPath(command) {
   ];
   for (const dir of dirs) {
     const candidate = join15(dir, command);
-    if (existsSync14(candidate)) return candidate;
+    if (existsSync15(candidate)) return candidate;
   }
   return null;
 }
@@ -6433,8 +6591,17 @@ async function capture() {
       hookLog(`capture cwd=${real} event=Stop -> only ${exchanges} exchange(s) (<${MIN_EXCHANGES_FOR_EXTRACTION}, skipped)`);
       return;
     }
+    const throttleId = data.session_id || null;
+    const lastProcessed = throttleId ? lastProcessedExchanges(readHookState(), throttleId) : 0;
+    if (throttleId && exchanges - lastProcessed < THROTTLE_MIN_NEW_EXCHANGES) {
+      hookLog(
+        `capture cwd=${real} event=Stop -> throttled (exchanges=${exchanges} lastProcessed=${lastProcessed}, need +${THROTTLE_MIN_NEW_EXCHANGES})`
+      );
+      return;
+    }
     const session = "hook-" + (data.session_id || newSessionId());
     const n = await extractAndSaveFacts(brain, cfg, history, session);
+    if (throttleId) saveHookState(throttleId, exchanges);
     hookLog(`capture cwd=${real} event=Stop -> saved ${n} fact${n === 1 ? "" : "s"}`);
     if (n > 0) process.stderr.write(`holt hook capture: saved ${n} fact${n === 1 ? "" : "s"} to ${memDir()}
 `);
@@ -6507,7 +6674,7 @@ async function hook(sub, rest = []) {
 
 // src/commands/run.ts
 import { writeFileSync as writeFileSync13 } from "fs";
-import { resolve as resolve5 } from "path";
+import { resolve as resolve6 } from "path";
 var USAGE3 = [
   "  holt run <task> [options]",
   "",
@@ -6596,7 +6763,7 @@ async function run(args) {
     process.stdout.write("\n");
   }
   if (p.out) {
-    const target = resolve5(process.cwd(), p.out);
+    const target = resolve6(process.cwd(), p.out);
     try {
       writeFileSync13(target, result.text, "utf8");
       process.stderr.write(c.dim(`saved to ${target}`) + "\n");
@@ -6609,11 +6776,11 @@ async function run(args) {
 
 // src/commands/schedule.ts
 import { spawnSync as spawnSync5 } from "child_process";
-import { writeFileSync as writeFileSync15, mkdirSync as mkdirSync13, rmSync as rmSync6, existsSync as existsSync15 } from "fs";
-import { dirname as dirname6 } from "path";
+import { writeFileSync as writeFileSync15, mkdirSync as mkdirSync13, rmSync as rmSync6, existsSync as existsSync16 } from "fs";
+import { dirname as dirname7 } from "path";
 
 // src/scheduler.ts
-import { homedir as homedir4 } from "os";
+import { homedir as homedir5 } from "os";
 import { join as join16 } from "path";
 import { readFileSync as readFileSync16, writeFileSync as writeFileSync14, mkdirSync as mkdirSync12 } from "fs";
 import { randomUUID as randomUUID4 } from "crypto";
@@ -6628,7 +6795,7 @@ function logPath(id) {
   return join16(logsDir(), `${id}.log`);
 }
 function plistPath(id) {
-  return join16(homedir4(), "Library", "LaunchAgents", `com.holt.${id}.plist`);
+  return join16(homedir5(), "Library", "LaunchAgents", `com.holt.${id}.plist`);
 }
 function loadJobs() {
   try {
@@ -6774,7 +6941,7 @@ function parseAdd(rest) {
 }
 function installDarwin(job, holtPath) {
   const path = plistPath(job.id);
-  mkdirSync13(dirname6(path), { recursive: true });
+  mkdirSync13(dirname7(path), { recursive: true });
   writeFileSync15(path, buildLaunchdPlist(job, holtPath), "utf8");
   const res = spawnSync5("launchctl", ["load", "-w", path], { encoding: "utf8" });
   if (res.status === 0) {
@@ -6863,7 +7030,7 @@ function listCmd2() {
 }
 function removeDarwin(id) {
   const path = plistPath(id);
-  if (existsSync15(path)) {
+  if (existsSync16(path)) {
     spawnSync5("launchctl", ["unload", path], { encoding: "utf8" });
     try {
       rmSync6(path);
@@ -6926,8 +7093,8 @@ async function schedule(sub, rest = []) {
 
 // src/commands/routine.ts
 import { spawnSync as spawnSync6 } from "child_process";
-import { writeFileSync as writeFileSync17, mkdirSync as mkdirSync15, rmSync as rmSync7, existsSync as existsSync16 } from "fs";
-import { dirname as dirname7, resolve as resolve6 } from "path";
+import { writeFileSync as writeFileSync17, mkdirSync as mkdirSync15, rmSync as rmSync7, existsSync as existsSync17 } from "fs";
+import { dirname as dirname8, resolve as resolve7 } from "path";
 
 // src/routines.ts
 import { readFileSync as readFileSync17, writeFileSync as writeFileSync16, mkdirSync as mkdirSync14 } from "fs";
@@ -7008,7 +7175,7 @@ function routineJobId(name) {
 }
 function installDarwin2(job, holtPath) {
   const path = plistPath(job.id);
-  mkdirSync15(dirname7(path), { recursive: true });
+  mkdirSync15(dirname8(path), { recursive: true });
   writeFileSync17(path, buildLaunchdPlist(job, holtPath), "utf8");
   const res = spawnSync6("launchctl", ["load", "-w", path], { encoding: "utf8" });
   if (res.status === 0) {
@@ -7053,7 +7220,7 @@ function installSchedule(r) {
 }
 function removeScheduleDarwin(id) {
   const path = plistPath(id);
-  if (existsSync16(path)) {
+  if (existsSync17(path)) {
     spawnSync6("launchctl", ["unload", path], { encoding: "utf8" });
     try {
       rmSync7(path);
@@ -7247,7 +7414,7 @@ async function runCmd(rest) {
   if (!quiet && !streamed) process.stdout.write(result.text);
   if (!quiet && (streamed || result.text) && !result.text.endsWith("\n")) process.stdout.write("\n");
   if (outTarget) {
-    const target = resolve6(routine2.workspace, outTarget);
+    const target = resolve7(routine2.workspace, outTarget);
     try {
       writeFileSync17(target, result.text, "utf8");
       if (!quiet) process.stderr.write(c.dim(`saved to ${target}`) + "\n");
@@ -7632,7 +7799,7 @@ async function doctor() {
 
 // src/commands/write.ts
 import { writeFileSync as writeFileSync18 } from "fs";
-import { resolve as resolve7 } from "path";
+import { resolve as resolve8 } from "path";
 
 // src/antiai.ts
 var EM_DASH = String.fromCharCode(8212);
@@ -7810,7 +7977,7 @@ async function write(args) {
   draft = stripEmDash(draft).trimEnd();
   process.stdout.write(draft + "\n");
   if (p.out) {
-    const target = resolve7(process.cwd(), p.out);
+    const target = resolve8(process.cwd(), p.out);
     try {
       writeFileSync18(target, draft + "\n", "utf8");
       process.stderr.write(c.dim(`saved to ${target}`) + "\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holt-os/holt",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "An open-source personal agent OS: any LLM, private memory you can see and walk.",
   "type": "module",
   "license": "MIT",