reasonix 0.4.17 → 0.4.20

package/dist/index.js

@@ -47,8 +47,8 @@ function computeWait(attempt, initial, cap, retryAfter) {
 }
 function sleep(ms, signal) {
   if (ms <= 0) return Promise.resolve();
-  return new Promise((resolve5, reject) => {
-    const timer = setTimeout(resolve5, ms);
+  return new Promise((resolve6, reject) => {
+    const timer = setTimeout(resolve6, ms);
     if (signal) {
       const onAbort = () => {
         clearTimeout(timer);
@@ -499,9 +499,25 @@ function setByPath(target, path, value) {
 var ToolRegistry = class {
   _tools = /* @__PURE__ */ new Map();
   _autoFlatten;
+  /**
+   * When true, `dispatch` refuses any tool whose `readOnly` flag isn't
+   * set (and whose `readOnlyCheck` doesn't pass on the specific args).
+   * Drives `reasonix code`'s Plan Mode — the model can still explore
+   * via read tools but its writes and non-allowlisted shell calls are
+   * bounced until the user approves a submitted plan.
+   */
+  _planMode = false;
   constructor(opts = {}) {
     this._autoFlatten = opts.autoFlatten !== false;
   }
+  /** Enable / disable plan-mode enforcement at dispatch. */
+  setPlanMode(on) {
+    this._planMode = Boolean(on);
+  }
+  /** True when the registry is currently refusing non-readonly calls. */
+  get planMode() {
+    return this._planMode;
+  }
   register(def) {
     if (!def.name) throw new Error("tool requires a name");
     const internal = { ...def };
@@ -553,16 +569,38 @@ var ToolRegistry = class {
     if (tool.flatSchema && args && typeof args === "object" && hasDotKey(args)) {
       args = nestArguments(args);
     }
+    if (this._planMode && !isReadOnlyCall(tool, args)) {
+      return JSON.stringify({
+        error: `${name}: unavailable in plan mode \u2014 this is a read-only exploration phase. Use read_file / list_directory / search_files / directory_tree / web_search / allowlisted shell commands to investigate. Call submit_plan with your proposed plan when you're ready for the user's review.`
+      });
+    }
     try {
       const result = await tool.fn(args, { signal: opts.signal });
       return typeof result === "string" ? result : JSON.stringify(result);
     } catch (err) {
+      const e = err;
+      if (typeof e.toToolResult === "function") {
+        try {
+          return JSON.stringify(e.toToolResult());
+        } catch {
+        }
+      }
       return JSON.stringify({
-        error: `${err.name}: ${err.message}`
+        error: `${e.name}: ${e.message}`
       });
     }
   }
 };
+function isReadOnlyCall(tool, args) {
+  if (tool.readOnlyCheck) {
+    try {
+      return Boolean(tool.readOnlyCheck(args));
+    } catch {
+      return false;
+    }
+  }
+  return tool.readOnly === true;
+}
 function hasDotKey(obj) {
   for (const k of Object.keys(obj)) {
     if (k.includes(".")) return true;
@@ -949,6 +987,16 @@ var ToolCallRepair = class {
     this.opts = opts;
     this.storm = new StormBreaker(opts.stormWindow ?? 6, opts.stormThreshold ?? 3);
   }
+  /**
+   * Drop the StormBreaker's sliding window of recent (name, args)
+   * signatures. Called at the start of every user turn — a fresh user
+   * message is a new intent, so carrying old repetition state into it
+   * would turn a valid "try again with different input" flow into a
+   * false-positive block.
+   */
+  resetStorm() {
+    this.storm.reset();
+  }
   process(declaredCalls, reasoningContent, content = null) {
     const report = {
       scavenged: 0,
@@ -1401,6 +1449,7 @@ var CacheFirstLoop = class {
   async *step(userInput) {
     this._turn++;
     this.scratch.reset();
+    this.repair.resetStorm();
     this._turnAbort = new AbortController();
     const signal = this._turnAbort.signal;
     let pendingUser = userInput;
@@ -1488,8 +1537,8 @@ var CacheFirstLoop = class {
             }
           );
           for (let k = 0; k < budget; k++) {
-            const sample = queue.shift() ?? await new Promise((resolve5) => {
-              waiter = resolve5;
+            const sample = queue.shift() ?? await new Promise((resolve6) => {
+              waiter = resolve6;
             });
             yield {
               turn: this._turn,
@@ -1624,6 +1673,16 @@ var CacheFirstLoop = class {
         repair: report,
         branch: branchSummary
       };
+      if (report.stormsBroken > 0) {
+        const noteTail = report.notes.length ? ` \u2014 ${report.notes[report.notes.length - 1]}` : "";
+        const allSuppressed = repairedCalls.length === 0 && toolCalls.length > 0;
+        const phrase = allSuppressed ? `stopped the model from calling the same tool with identical args repeatedly (all ${toolCalls.length} call(s) this turn were already in the recent-repeat window). Likely a stuck retry \u2014 reword your instruction, rule out the underlying blocker, or try /retry after fixing it` : `suppressed ${report.stormsBroken} repeat tool call(s) that had fired 3+ times with identical args in a sliding window`;
+        yield {
+          turn: this._turn,
+          role: "warning",
+          content: `${phrase}${noteTail}`
+        };
+      }
       if (repairedCalls.length === 0) {
         yield { turn: this._turn, role: "done", content: assistantContent };
         return;
@@ -1891,6 +1950,291 @@ ${mem.content}
 `;
 }
 
+// src/user-memory.ts
+import { createHash as createHash2 } from "crypto";
+import {
+  existsSync as existsSync3,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync3,
+  readdirSync as readdirSync2,
+  unlinkSync as unlinkSync2,
+  writeFileSync as writeFileSync2
+} from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join3, resolve } from "path";
+var USER_MEMORY_DIR = "memory";
+var MEMORY_INDEX_FILE = "MEMORY.md";
+var MEMORY_INDEX_MAX_CHARS = 4e3;
+var VALID_NAME = /^[a-zA-Z0-9_-][a-zA-Z0-9_.-]{1,38}[a-zA-Z0-9]$/;
+function sanitizeMemoryName(raw) {
+  const trimmed = String(raw ?? "").trim();
+  if (!VALID_NAME.test(trimmed)) {
+    throw new Error(
+      `invalid memory name: ${JSON.stringify(raw)} \u2014 must be 3-40 chars, alnum/_/-, no path separators`
+    );
+  }
+  return trimmed;
+}
+function projectHash(rootDir) {
+  const abs = resolve(rootDir);
+  return createHash2("sha1").update(abs).digest("hex").slice(0, 16);
+}
+function scopeDir(opts) {
+  if (opts.scope === "global") {
+    return join3(opts.homeDir, USER_MEMORY_DIR, "global");
+  }
+  if (!opts.projectRoot) {
+    throw new Error("scope=project requires a projectRoot on MemoryStore");
+  }
+  return join3(opts.homeDir, USER_MEMORY_DIR, projectHash(opts.projectRoot));
+}
+function ensureDir(p) {
+  if (!existsSync3(p)) mkdirSync2(p, { recursive: true });
+}
+function parseFrontmatter(raw) {
+  const lines = raw.split(/\r?\n/);
+  if (lines[0] !== "---") return { data: {}, body: raw };
+  const end = lines.indexOf("---", 1);
+  if (end < 0) return { data: {}, body: raw };
+  const data = {};
+  for (let i = 1; i < end; i++) {
+    const line = lines[i];
+    if (!line) continue;
+    const m = line.match(/^([a-zA-Z_][a-zA-Z0-9_-]*):\s*(.*)$/);
+    if (m?.[1]) data[m[1]] = (m[2] ?? "").trim();
+  }
+  return {
+    data,
+    body: lines.slice(end + 1).join("\n").replace(/^\n+/, "")
+  };
+}
+function formatFrontmatter(e) {
+  return [
+    "---",
+    `name: ${e.name}`,
+    `description: ${e.description.replace(/\n/g, " ")}`,
+    `type: ${e.type}`,
+    `scope: ${e.scope}`,
+    `created: ${e.createdAt}`,
+    "---",
+    ""
+  ].join("\n");
+}
+function todayIso() {
+  const d = /* @__PURE__ */ new Date();
+  return d.toISOString().slice(0, 10);
+}
+function indexLine(e) {
+  const safeDesc = e.description.replace(/\n/g, " ").trim();
+  const max = 130 - e.name.length;
+  const clipped = safeDesc.length > max ? `${safeDesc.slice(0, Math.max(1, max - 1))}\u2026` : safeDesc;
+  return `- [${e.name}](${e.name}.md) \u2014 ${clipped}`;
+}
+var MemoryStore = class {
+  homeDir;
+  projectRoot;
+  constructor(opts = {}) {
+    this.homeDir = opts.homeDir ?? join3(homedir2(), ".reasonix");
+    this.projectRoot = opts.projectRoot ? resolve(opts.projectRoot) : void 0;
+  }
+  /** Directory this store writes `scope` files into, creating it if needed. */
+  dir(scope) {
+    const d = scopeDir({ homeDir: this.homeDir, scope, projectRoot: this.projectRoot });
+    ensureDir(d);
+    return d;
+  }
+  /** Absolute path to a memory file (no existence check). */
+  pathFor(scope, name) {
+    return join3(this.dir(scope), `${sanitizeMemoryName(name)}.md`);
+  }
+  /** True iff this store is configured with a project scope available. */
+  hasProjectScope() {
+    return this.projectRoot !== void 0;
+  }
+  /**
+   * Read the `MEMORY.md` index for a scope. Returns post-cap content
+   * (with a truncation marker if clipped), or `null` when absent / empty.
+   */
+  loadIndex(scope) {
+    if (scope === "project" && !this.projectRoot) return null;
+    const file = join3(
+      scopeDir({ homeDir: this.homeDir, scope, projectRoot: this.projectRoot }),
+      MEMORY_INDEX_FILE
+    );
+    if (!existsSync3(file)) return null;
+    let raw;
+    try {
+      raw = readFileSync3(file, "utf8");
+    } catch {
+      return null;
+    }
+    const trimmed = raw.trim();
+    if (!trimmed) return null;
+    const originalChars = trimmed.length;
+    const truncated = originalChars > MEMORY_INDEX_MAX_CHARS;
+    const content = truncated ? `${trimmed.slice(0, MEMORY_INDEX_MAX_CHARS)}
+\u2026 (truncated ${originalChars - MEMORY_INDEX_MAX_CHARS} chars)` : trimmed;
+    return { content, originalChars, truncated };
+  }
+  /** Read one memory file's body (frontmatter stripped). Throws if missing. */
+  read(scope, name) {
+    const file = this.pathFor(scope, name);
+    if (!existsSync3(file)) {
+      throw new Error(`memory not found: scope=${scope} name=${name}`);
+    }
+    const raw = readFileSync3(file, "utf8");
+    const { data, body } = parseFrontmatter(raw);
+    return {
+      name: data.name ?? name,
+      type: data.type ?? "project",
+      scope: data.scope ?? scope,
+      description: data.description ?? "",
+      body: body.trim(),
+      createdAt: data.created ?? ""
+    };
+  }
+  /**
+   * List every memory in this store. Scans both scopes (skips project
+   * scope if unconfigured). Silently skips malformed files; the index
+   * must stay queryable even if one file is hand-edited into nonsense.
+   */
+  list() {
+    const out = [];
+    const scopes = this.projectRoot ? ["global", "project"] : ["global"];
+    for (const scope of scopes) {
+      const dir = scopeDir({ homeDir: this.homeDir, scope, projectRoot: this.projectRoot });
+      if (!existsSync3(dir)) continue;
+      let entries;
+      try {
+        entries = readdirSync2(dir);
+      } catch {
+        continue;
+      }
+      for (const entry of entries) {
+        if (entry === MEMORY_INDEX_FILE) continue;
+        if (!entry.endsWith(".md")) continue;
+        const name = entry.slice(0, -3);
+        try {
+          out.push(this.read(scope, name));
+        } catch {
+        }
+      }
+    }
+    return out;
+  }
+  /**
+   * Write a new memory (or overwrite existing). Creates the scope dir,
+   * writes the `.md` file, and regenerates `MEMORY.md`. Returns the
+   * absolute path written to.
+   */
+  write(input) {
+    if (input.scope === "project" && !this.projectRoot) {
+      throw new Error("cannot write project-scoped memory: no projectRoot configured");
+    }
+    const name = sanitizeMemoryName(input.name);
+    const desc = String(input.description ?? "").trim();
+    if (!desc) throw new Error("memory description cannot be empty");
+    const body = String(input.body ?? "").trim();
+    if (!body) throw new Error("memory body cannot be empty");
+    const entry = {
+      ...input,
+      name,
+      description: desc,
+      body,
+      createdAt: todayIso()
+    };
+    const dir = this.dir(input.scope);
+    const file = join3(dir, `${name}.md`);
+    const content = `${formatFrontmatter(entry)}${body}
+`;
+    writeFileSync2(file, content, "utf8");
+    this.regenerateIndex(input.scope);
+    return file;
+  }
+  /** Delete one memory + its index line. No-op if the file is already gone. */
+  delete(scope, rawName) {
+    if (scope === "project" && !this.projectRoot) {
+      throw new Error("cannot delete project-scoped memory: no projectRoot configured");
+    }
+    const file = this.pathFor(scope, rawName);
+    if (!existsSync3(file)) return false;
+    unlinkSync2(file);
+    this.regenerateIndex(scope);
+    return true;
+  }
+  /**
+   * Rebuild `MEMORY.md` from the `.md` files currently in the scope dir.
+   * Called after every write/delete. Sorted by name for stable prefix
+   * hashing — two stores with the same set of files produce byte-identical
+   * MEMORY.md content, keeping the cache prefix reproducible.
+   */
+  regenerateIndex(scope) {
+    const dir = scopeDir({ homeDir: this.homeDir, scope, projectRoot: this.projectRoot });
+    if (!existsSync3(dir)) return;
+    let files;
+    try {
+      files = readdirSync2(dir);
+    } catch {
+      return;
+    }
+    const mdFiles = files.filter((f) => f !== MEMORY_INDEX_FILE && f.endsWith(".md")).sort((a, b) => a.localeCompare(b));
+    const indexPath = join3(dir, MEMORY_INDEX_FILE);
+    if (mdFiles.length === 0) {
+      if (existsSync3(indexPath)) unlinkSync2(indexPath);
+      return;
+    }
+    const lines = [];
+    for (const f of mdFiles) {
+      const name = f.slice(0, -3);
+      try {
+        const entry = this.read(scope, name);
+        lines.push(indexLine({ name: entry.name || name, description: entry.description }));
+      } catch {
+        lines.push(`- [${name}](${name}.md) \u2014 (malformed, check frontmatter)`);
+      }
+    }
+    writeFileSync2(indexPath, `${lines.join("\n")}
+`, "utf8");
+  }
+};
+function applyUserMemory(basePrompt, opts = {}) {
+  if (!memoryEnabled()) return basePrompt;
+  const store = new MemoryStore(opts);
+  const global = store.loadIndex("global");
+  const project = store.hasProjectScope() ? store.loadIndex("project") : null;
+  if (!global && !project) return basePrompt;
+  const parts = [basePrompt];
+  if (global) {
+    parts.push(
+      "",
+      "# User memory \u2014 global (~/.reasonix/memory/global/MEMORY.md)",
+      "",
+      "Cross-project facts and preferences the user has told you in prior sessions. TREAT AS AUTHORITATIVE \u2014 don't re-verify via filesystem or web. One-liners index detail files; call `recall_memory` for full bodies only when the one-liner isn't enough.",
+      "",
+      "```",
+      global.content,
+      "```"
+    );
+  }
+  if (project) {
+    parts.push(
+      "",
+      "# User memory \u2014 this project",
+      "",
+      "Per-project facts the user established in prior sessions (not committed to the repo). TREAT AS AUTHORITATIVE. Same recall pattern as global memory.",
+      "",
+      "```",
+      project.content,
+      "```"
+    );
+  }
+  return parts.join("\n");
+}
+function applyMemoryStack(basePrompt, rootDir) {
+  const withProject = applyProjectMemory(basePrompt, rootDir);
+  return applyUserMemory(withProject, { projectRoot: rootDir });
+}
+
 // src/tools/filesystem.ts
 import { promises as fs } from "fs";
 import * as pathMod from "path";
@@ -1916,6 +2260,7 @@ function registerFilesystemTools(registry, opts) {
   registry.register({
     name: "read_file",
     description: "Read a file under the sandbox root. Returns the full contents (truncated with a notice if larger than the per-call cap). Paths may be relative to the root or absolute-under-root.",
+    readOnly: true,
     parameters: {
       type: "object",
       properties: {
@@ -1953,6 +2298,7 @@ function registerFilesystemTools(registry, opts) {
   registry.register({
     name: "list_directory",
     description: "List entries in a directory under the sandbox root. Returns one line per entry, marking directories with a trailing slash. Not recursive \u2014 use directory_tree for that.",
+    readOnly: true,
     parameters: {
       type: "object",
       properties: {
@@ -1972,6 +2318,7 @@ function registerFilesystemTools(registry, opts) {
   registry.register({
     name: "directory_tree",
     description: "Recursively list entries in a directory. Shows indented tree structure with directories marked '/'. Caps output so a huge tree doesn't drown the context.",
+    readOnly: true,
     parameters: {
       type: "object",
       properties: {
@@ -2018,6 +2365,7 @@ function registerFilesystemTools(registry, opts) {
   registry.register({
     name: "search_files",
     description: "Find files whose NAME matches a substring or regex. Case-insensitive. Walks the directory recursively under the sandbox root. Returns one path per line.",
+    readOnly: true,
     parameters: {
       type: "object",
       properties: {
@@ -2070,6 +2418,7 @@ function registerFilesystemTools(registry, opts) {
   registry.register({
     name: "get_file_info",
     description: "Stat a path under the sandbox root. Returns type (file|directory|symlink), size in bytes, mtime in ISO-8601.",
+    readOnly: true,
     parameters: {
       type: "object",
       properties: {
@@ -2109,7 +2458,7 @@ function registerFilesystemTools(registry, opts) {
   });
   registry.register({
     name: "edit_file",
-    description: "Apply a SEARCH/REPLACE edit to an existing file. `search` must match exactly (whitespace sensitive) \u2014 no regex. The match must be unique in the file; otherwise the edit is refused to avoid surprise rewrites. This flat-string shape replaces the `{oldText, newText}[]` JSON array form that previously triggered R1 DSML hallucinations.",
+    description: "Apply a SEARCH/REPLACE edit to an existing file. `search` must match exactly (whitespace sensitive) \u2014 no regex. The match must be unique in the file; otherwise the edit is refused to avoid surprise rewrites.",
     parameters: {
       type: "object",
       properties: {
@@ -2226,8 +2575,175 @@ function lineDiff(a, b) {
   return out;
 }
 
+// src/tools/memory.ts
+function registerMemoryTools(registry, opts = {}) {
+  const store = new MemoryStore({ homeDir: opts.homeDir, projectRoot: opts.projectRoot });
+  const hasProject = store.hasProjectScope();
+  registry.register({
+    name: "remember",
+    description: "Save a memory for future sessions. Use when the user states a preference, corrects your approach, shares a non-obvious fact about this project, or explicitly asks you to remember something. Don't remember transient task state \u2014 only things worth recalling next session. The memory is written now but won't re-load into the system prompt until the next `/new` or launch.",
+    parameters: {
+      type: "object",
+      properties: {
+        type: {
+          type: "string",
+          enum: ["user", "feedback", "project", "reference"],
+          description: "'user' = role/skills/prefs; 'feedback' = corrections or confirmed approaches; 'project' = facts/decisions about the current work; 'reference' = pointers to external systems the user uses."
+        },
+        scope: {
+          type: "string",
+          enum: ["global", "project"],
+          description: "'global' = applies across every project (preferences, tooling); 'project' = scoped to the current sandbox (decisions, local facts). Only available in `reasonix code`."
+        },
+        name: {
+          type: "string",
+          description: "filename-safe identifier, 3-40 chars, alnum + _ - . (no path separators, no leading dot)."
+        },
+        description: {
+          type: "string",
+          description: "One-line summary shown in MEMORY.md (under ~150 chars)."
+        },
+        content: {
+          type: "string",
+          description: "Full memory body in markdown. For feedback/project types, structure as: rule/fact, then **Why:** line, then **How to apply:** line."
+        }
+      },
+      required: ["type", "scope", "name", "description", "content"]
+    },
+    fn: async (args) => {
+      if (args.scope === "project" && !hasProject) {
+        return JSON.stringify({
+          error: "scope='project' is unavailable in this session (no sandbox root). Retry with scope='global', or ask the user to switch to `reasonix code` for project-scoped memory."
+        });
+      }
+      try {
+        const path = store.write({
+          name: args.name,
+          type: args.type,
+          scope: args.scope,
+          description: args.description,
+          body: args.content
+        });
+        const key = sanitizeMemoryName(args.name);
+        return [
+          `\u2713 REMEMBERED (${args.scope}/${key}): ${args.description}`,
+          "",
+          "TREAT THIS AS ESTABLISHED FACT for the rest of this session.",
+          "The user just told you \u2014 don't re-explore the filesystem to re-derive it.",
+          `(Saved to ${path}; pins into the system prompt on next /new or launch.)`
+        ].join("\n");
+      } catch (err) {
+        return JSON.stringify({ error: `remember failed: ${err.message}` });
+      }
+    }
+  });
+  registry.register({
+    name: "forget",
+    description: "Delete a memory file and remove it from MEMORY.md. Use when the user explicitly asks to forget something, or when a previously-remembered fact has become wrong. Irreversible \u2014 no tombstone.",
+    parameters: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Memory name (the identifier used in `remember`)." },
+        scope: { type: "string", enum: ["global", "project"] }
+      },
+      required: ["name", "scope"]
+    },
+    fn: async (args) => {
+      if (args.scope === "project" && !hasProject) {
+        return JSON.stringify({
+          error: "scope='project' is unavailable in this session (no sandbox root)."
+        });
+      }
+      try {
+        const existed = store.delete(args.scope, args.name);
+        return existed ? `forgot (${args.scope}/${sanitizeMemoryName(args.name)}). Re-load on next /new or launch.` : `no such memory: ${args.scope}/${args.name} (nothing to forget).`;
+      } catch (err) {
+        return JSON.stringify({ error: `forget failed: ${err.message}` });
+      }
+    }
+  });
+  registry.register({
+    name: "recall_memory",
+    description: "Read the full body of a memory file when its MEMORY.md one-liner (already in the system prompt) isn't enough detail. Most of the time the index suffices \u2014 only call this when the user's question genuinely requires the full context.",
+    readOnly: true,
+    parameters: {
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        scope: { type: "string", enum: ["global", "project"] }
+      },
+      required: ["name", "scope"]
+    },
+    fn: async (args) => {
+      if (args.scope === "project" && !hasProject) {
+        return JSON.stringify({
+          error: "scope='project' is unavailable in this session (no sandbox root)."
+        });
+      }
+      try {
+        const entry = store.read(args.scope, args.name);
+        return [
+          `# ${entry.name}  (${entry.scope}/${entry.type}, created ${entry.createdAt || "?"})`,
+          entry.description ? `> ${entry.description}` : "",
+          "",
+          entry.body
+        ].filter(Boolean).join("\n");
+      } catch (err) {
+        return JSON.stringify({ error: `recall failed: ${err.message}` });
+      }
+    }
+  });
+  return registry;
+}
+
+// src/tools/plan.ts
+var PlanProposedError = class extends Error {
+  plan;
+  constructor(plan) {
+    super(
+      "PlanProposedError: plan submitted. STOP calling tools now \u2014 the TUI has shown the plan to the user. Wait for their next message; it will either approve (you'll then implement the plan), request a refinement (you should explore more and submit an updated plan), or cancel (drop the plan and ask what they want instead). Don't call any tools in the meantime."
+    );
+    this.name = "PlanProposedError";
+    this.plan = plan;
+  }
+  /**
+   * Structured tool-result shape. Consumed by the TUI to extract the
+   * plan without regex-scraping the error message.
+   */
+  toToolResult() {
+    return { error: `${this.name}: ${this.message}`, plan: this.plan };
+  }
+};
+function registerPlanTool(registry, opts = {}) {
+  registry.register({
+    name: "submit_plan",
+    description: "Submit a concrete plan to the user for review before executing. Use this for tasks that warrant a review gate \u2014 multi-file refactors, architecture changes, anything that would be expensive or confusing to undo. Skip it for small fixes (one-line typo, obvious bug with a clear fix) \u2014 just make the change. The user will either approve (you then implement it), ask for refinement, or cancel. If the user has already enabled /plan mode, writes are blocked at dispatch and you MUST use this. Write the plan as markdown with a one-line summary, a bulleted list of files to touch and what will change, and any risks or open questions.",
+    readOnly: true,
+    parameters: {
+      type: "object",
+      properties: {
+        plan: {
+          type: "string",
+          description: "Markdown-formatted plan. Lead with a one-sentence summary. Then a file-by-file breakdown of what you'll change and why. Flag any risks or open questions at the end so the user can weigh in before you start."
+        }
+      },
+      required: ["plan"]
+    },
+    fn: async (args) => {
+      const plan = (args?.plan ?? "").trim();
+      if (!plan) {
+        throw new Error("submit_plan: empty plan \u2014 write a markdown plan and try again.");
+      }
+      opts.onPlanSubmitted?.(plan);
+      throw new PlanProposedError(plan);
+    }
+  });
+  return registry;
+}
+
 // src/tools/shell.ts
 import { spawn } from "child_process";
+import { existsSync as existsSync4, statSync as statSync2 } from "fs";
 import * as pathMod2 from "path";
 var DEFAULT_TIMEOUT_SEC = 60;
 var DEFAULT_MAX_OUTPUT_CHARS = 32e3;
@@ -2345,10 +2861,12 @@ async function runCommand(cmd, opts) {
     windowsHide: true,
     env: process.env
   };
-  return await new Promise((resolve5, reject) => {
+  const { bin, args, spawnOverrides } = prepareSpawn(argv);
+  const effectiveSpawnOpts = { ...spawnOpts, ...spawnOverrides };
+  return await new Promise((resolve6, reject) => {
     let child;
     try {
-      child = spawn(argv[0], argv.slice(1), spawnOpts);
+      child = spawn(bin, args, effectiveSpawnOpts);
     } catch (err) {
       reject(err);
       return;
@@ -2378,10 +2896,63 @@ async function runCommand(cmd, opts) {
       const output = buf.length > maxChars ? `${buf.slice(0, maxChars)}
 
 [\u2026 truncated ${buf.length - maxChars} chars \u2026]` : buf;
-      resolve5({ exitCode: code, output, timedOut });
+      resolve6({ exitCode: code, output, timedOut });
     });
   });
 }
+function resolveExecutable(cmd, opts = {}) {
+  const platform = opts.platform ?? process.platform;
+  if (platform !== "win32") return cmd;
+  if (!cmd) return cmd;
+  if (cmd.includes("/") || cmd.includes("\\") || pathMod2.isAbsolute(cmd)) return cmd;
+  if (pathMod2.extname(cmd)) return cmd;
+  const env = opts.env ?? process.env;
+  const pathExt = (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").map((e) => e.trim()).filter(Boolean);
+  const delimiter2 = opts.pathDelimiter ?? (platform === "win32" ? ";" : pathMod2.delimiter);
+  const pathDirs = (env.PATH ?? "").split(delimiter2).filter(Boolean);
+  const isFile = opts.isFile ?? defaultIsFile;
+  for (const dir of pathDirs) {
+    for (const ext of pathExt) {
+      const full = pathMod2.win32.join(dir, cmd + ext);
+      if (isFile(full)) return full;
+    }
+  }
+  return cmd;
+}
+function defaultIsFile(full) {
+  try {
+    return existsSync4(full) && statSync2(full).isFile();
+  } catch {
+    return false;
+  }
+}
+function prepareSpawn(argv, opts = {}) {
+  const head = argv[0] ?? "";
+  const tail = argv.slice(1);
+  const platform = opts.platform ?? process.platform;
+  const resolved = resolveExecutable(head, opts);
+  if (platform !== "win32") {
+    return { bin: resolved, args: [...tail], spawnOverrides: {} };
+  }
+  if (/\.(cmd|bat)$/i.test(resolved)) {
+    const cmdline = [resolved, ...tail].map(quoteForCmdExe).join(" ");
+    return {
+      bin: "cmd.exe",
+      args: ["/d", "/s", "/c", cmdline],
+      // windowsVerbatimArguments prevents Node from re-quoting the /c
+      // payload — we've already composed an exact cmd.exe command
+      // line. Without this Node wraps our already-quoted string in
+      // another round of quotes and cmd.exe can't parse it.
+      spawnOverrides: { windowsVerbatimArguments: true }
+    };
+  }
+  return { bin: resolved, args: [...tail], spawnOverrides: {} };
+}
+function quoteForCmdExe(arg) {
+  if (arg === "") return '""';
+  if (!/[\s"&|<>^%(),;!]/.test(arg)) return arg;
+  return `"${arg.replace(/"/g, '""')}"`;
+}
 var NeedsConfirmationError = class extends Error {
   command;
   constructor(command) {
@@ -2400,13 +2971,23 @@ function registerShellTools(registry, opts) {
   const allowAll = opts.allowAll ?? false;
   registry.register({
     name: "run_command",
-    description: "Run a shell command in the project root and return its combined stdout+stderr. Read-only and test commands (git status, ls, npm test, pytest, cargo test, grep, etc.) run immediately. Anything that could mutate state (npm install, git commit, rm, chmod) is refused and the user has to confirm in the TUI. Prefer this over asking the user to run a command manually \u2014 after edits, run the project's tests to verify.",
+    description: "Run a shell command in the project root and return its combined stdout+stderr. Common read-only inspection and test/lint/typecheck commands run immediately; anything that could mutate state, install dependencies, or touch the network is refused until the user confirms it in the TUI. Prefer this over asking the user to run a command manually \u2014 after edits, run the project's tests to verify.",
+    // Plan-mode gate: allow allowlisted commands through (git status,
+    // cargo check, ls, grep …) so the model can actually investigate
+    // during planning. Anything that would otherwise trigger a
+    // confirmation prompt is treated as "not read-only" and bounced.
+    readOnlyCheck: (args) => {
+      if (allowAll) return true;
+      const cmd = typeof args?.command === "string" ? args.command.trim() : "";
+      if (!cmd) return false;
+      return isAllowed(cmd, extraAllowed);
+    },
     parameters: {
       type: "object",
       properties: {
         command: {
           type: "string",
-          description: "Full command line, e.g. 'npm test' or 'git diff src/foo.ts'. Tokenized with POSIX-ish quoting; no shell expansion, no pipes, no redirects."
+          description: "Full command line. Tokenized with POSIX-ish quoting; no shell expansion, no pipes, no redirects."
         },
         timeoutSec: {
           type: "integer",
@@ -2567,6 +3148,7 @@ function registerWebTools(registry, opts = {}) {
   registry.register({
     name: "web_search",
     description: "Search the public web. Returns ranked results with title, url, and snippet. Use this when the question needs information more current than your training data, when you're unsure of a factual detail, or when the user asks about a specific webpage/library/release you haven't seen.",
+    readOnly: true,
     parameters: {
       type: "object",
       properties: {
@@ -2589,6 +3171,7 @@ function registerWebTools(registry, opts = {}) {
   registry.register({
     name: "web_fetch",
     description: "Download a URL and return its visible text content (HTML pages get scripts/styles/nav stripped). Truncated at the tool-result cap. Use after web_search when a snippet isn't enough.",
+    readOnly: true,
     parameters: {
       type: "object",
       properties: {
@@ -2623,12 +3206,12 @@ ${i + 1}. ${r.title}`);
 }
 
 // src/env.ts
-import { readFileSync as readFileSync3 } from "fs";
-import { resolve as resolve3 } from "path";
+import { readFileSync as readFileSync4 } from "fs";
+import { resolve as resolve4 } from "path";
 function loadDotenv(path = ".env") {
   let raw;
   try {
-    raw = readFileSync3(resolve3(process.cwd(), path), "utf8");
+    raw = readFileSync4(resolve4(process.cwd(), path), "utf8");
   } catch {
     return;
   }
@@ -2647,7 +3230,7 @@ function loadDotenv(path = ".env") {
 }
 
 // src/transcript.ts
-import { createWriteStream, readFileSync as readFileSync4 } from "fs";
+import { createWriteStream, readFileSync as readFileSync5 } from "fs";
 function recordFromLoopEvent(ev, extra) {
   const rec = {
     ts: (/* @__PURE__ */ new Date()).toISOString(),
@@ -2698,7 +3281,7 @@ function openTranscriptFile(path, meta) {
   return stream;
 }
 function readTranscript(path) {
-  const raw = readFileSync4(path, "utf8");
+  const raw = readFileSync5(path, "utf8");
   return parseTranscript(raw);
 }
 function isPlanStateEmptyShape(s) {
@@ -3310,7 +3893,7 @@ var McpClient = class {
     const id = this.nextId++;
     const frame = { jsonrpc: "2.0", id, method, params };
     let abortHandler = null;
-    const promise = new Promise((resolve5, reject) => {
+    const promise = new Promise((resolve6, reject) => {
       const timeout = setTimeout(() => {
         this.pending.delete(id);
         if (abortHandler && signal) signal.removeEventListener("abort", abortHandler);
@@ -3319,7 +3902,7 @@ var McpClient = class {
         );
       }, this.requestTimeoutMs);
       this.pending.set(id, {
-        resolve: resolve5,
+        resolve: resolve6,
         reject,
         timeout
       });
@@ -3442,12 +4025,12 @@ var StdioTransport = class {
   }
   async send(message) {
     if (this.closed) throw new Error("MCP transport is closed");
-    return new Promise((resolve5, reject) => {
+    return new Promise((resolve6, reject) => {
       const line = `${JSON.stringify(message)}
 `;
       this.child.stdin.write(line, "utf8", (err) => {
         if (err) reject(err);
-        else resolve5();
+        else resolve6();
       });
     });
   }
@@ -3458,8 +4041,8 @@ var StdioTransport = class {
         continue;
       }
       if (this.closed) return;
-      const next = await new Promise((resolve5) => {
-        this.waiters.push(resolve5);
+      const next = await new Promise((resolve6) => {
+        this.waiters.push(resolve6);
       });
       if (next === null) return;
       yield next;
@@ -3525,8 +4108,8 @@ var SseTransport = class {
   constructor(opts) {
     this.url = opts.url;
     this.headers = opts.headers ?? {};
-    this.endpointReady = new Promise((resolve5, reject) => {
-      this.resolveEndpoint = resolve5;
+    this.endpointReady = new Promise((resolve6, reject) => {
+      this.resolveEndpoint = resolve6;
       this.rejectEndpoint = reject;
     });
     this.endpointReady.catch(() => void 0);
@@ -3553,8 +4136,8 @@ var SseTransport = class {
         continue;
       }
       if (this.closed) return;
-      const next = await new Promise((resolve5) => {
-        this.waiters.push(resolve5);
+      const next = await new Promise((resolve6) => {
+        this.waiters.push(resolve6);
       });
       if (next === null) return;
       yield next;
@@ -3753,8 +4336,8 @@ async function trySection(load) {
 }
 
 // src/code/edit-blocks.ts
-import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync5, unlinkSync as unlinkSync2, writeFileSync as writeFileSync2 } from "fs";
-import { dirname as dirname3, resolve as resolve4 } from "path";
+import { existsSync as existsSync5, mkdirSync as mkdirSync3, readFileSync as readFileSync6, unlinkSync as unlinkSync3, writeFileSync as writeFileSync3 } from "fs";
+import { dirname as dirname3, resolve as resolve5 } from "path";
 var BLOCK_RE = /^(\S[^\n]*)\n<{7} SEARCH\n([\s\S]*?)\n?={7}\n([\s\S]*?)\n?>{7} REPLACE/gm;
 function parseEditBlocks(text) {
   const out = [];
@@ -3772,8 +4355,8 @@ function parseEditBlocks(text) {
   return out;
 }
 function applyEditBlock(block, rootDir) {
-  const absRoot = resolve4(rootDir);
-  const absTarget = resolve4(absRoot, block.path);
+  const absRoot = resolve5(rootDir);
+  const absTarget = resolve5(absRoot, block.path);
   if (absTarget !== absRoot && !absTarget.startsWith(`${absRoot}${sep()}`)) {
     return {
       path: block.path,
@@ -3782,7 +4365,7 @@ function applyEditBlock(block, rootDir) {
     };
   }
   const searchEmpty = block.search.length === 0;
-  const exists = existsSync3(absTarget);
+  const exists = existsSync5(absTarget);
   try {
     if (!exists) {
       if (!searchEmpty) {
@@ -3792,11 +4375,11 @@ function applyEditBlock(block, rootDir) {
           message: "file does not exist; to create it, use an empty SEARCH block"
         };
       }
-      mkdirSync2(dirname3(absTarget), { recursive: true });
-      writeFileSync2(absTarget, block.replace, "utf8");
+      mkdirSync3(dirname3(absTarget), { recursive: true });
+      writeFileSync3(absTarget, block.replace, "utf8");
       return { path: block.path, status: "created" };
     }
-    const content = readFileSync5(absTarget, "utf8");
+    const content = readFileSync6(absTarget, "utf8");
     if (searchEmpty) {
       return {
         path: block.path,
@@ -3813,7 +4396,7 @@ function applyEditBlock(block, rootDir) {
       };
     }
     const replaced = `${content.slice(0, idx)}${block.replace}${content.slice(idx + block.search.length)}`;
-    writeFileSync2(absTarget, replaced, "utf8");
+    writeFileSync3(absTarget, replaced, "utf8");
     return { path: block.path, status: "applied" };
   } catch (err) {
     return { path: block.path, status: "error", message: err.message };
@@ -3823,19 +4406,19 @@ function applyEditBlocks(blocks, rootDir) {
   return blocks.map((b) => applyEditBlock(b, rootDir));
 }
 function snapshotBeforeEdits(blocks, rootDir) {
-  const absRoot = resolve4(rootDir);
+  const absRoot = resolve5(rootDir);
   const seen = /* @__PURE__ */ new Set();
   const snapshots = [];
   for (const b of blocks) {
     if (seen.has(b.path)) continue;
     seen.add(b.path);
-    const abs = resolve4(absRoot, b.path);
-    if (!existsSync3(abs)) {
+    const abs = resolve5(absRoot, b.path);
+    if (!existsSync5(abs)) {
       snapshots.push({ path: b.path, prevContent: null });
       continue;
     }
     try {
-      snapshots.push({ path: b.path, prevContent: readFileSync5(abs, "utf8") });
+      snapshots.push({ path: b.path, prevContent: readFileSync6(abs, "utf8") });
     } catch {
       snapshots.push({ path: b.path, prevContent: null });
     }
@@ -3843,9 +4426,9 @@ function snapshotBeforeEdits(blocks, rootDir) {
   return snapshots;
 }
 function restoreSnapshots(snapshots, rootDir) {
-  const absRoot = resolve4(rootDir);
+  const absRoot = resolve5(rootDir);
   return snapshots.map((snap) => {
-    const abs = resolve4(absRoot, snap.path);
+    const abs = resolve5(absRoot, snap.path);
     if (abs !== absRoot && !abs.startsWith(`${absRoot}${sep()}`)) {
       return {
         path: snap.path,
@@ -3855,14 +4438,14 @@ function restoreSnapshots(snapshots, rootDir) {
     }
     try {
       if (snap.prevContent === null) {
-        if (existsSync3(abs)) unlinkSync2(abs);
+        if (existsSync5(abs)) unlinkSync3(abs);
         return {
           path: snap.path,
           status: "applied",
           message: "removed (the edit had created it)"
         };
       }
-      writeFileSync2(abs, snap.prevContent, "utf8");
+      writeFileSync3(abs, snap.prevContent, "utf8");
       return {
         path: snap.path,
         status: "applied",
@@ -3878,10 +4461,31 @@ function sep() {
 }
 
 // src/code/prompt.ts
-import { existsSync as existsSync4, readFileSync as readFileSync6 } from "fs";
-import { join as join4 } from "path";
+import { existsSync as existsSync6, readFileSync as readFileSync7 } from "fs";
+import { join as join5 } from "path";
 var CODE_SYSTEM_PROMPT = `You are Reasonix Code, a coding assistant. You have filesystem tools (read_file, write_file, list_directory, search_files, etc.) rooted at the user's working directory.
 
+# When to propose a plan (submit_plan)
+
+You have a \`submit_plan\` tool that shows the user a markdown plan and lets them Approve / Refine / Cancel before you execute. Use it proactively when the task is large enough to deserve a review gate:
+
+- Multi-file refactors or renames.
+- Architecture changes (moving modules, splitting / merging files, new abstractions).
+- Anything where "undo" after the fact would be expensive \u2014 migrations, destructive cleanups, API shape changes.
+- When the user's request is ambiguous and multiple reasonable interpretations exist \u2014 propose your reading as a plan and let them confirm.
+
+Skip submit_plan for small, obvious changes: one-line typo, clear bug with a clear fix, adding a missing import, renaming a local variable. Just do those.
+
+Plan body: one-sentence summary, then a file-by-file breakdown of what you'll change and why, and any risks or open questions. If some decisions are genuinely up to the user (naming, tradeoffs, out-of-scope possibilities), list them in an "Open questions" section \u2014 the user sees the plan in a picker and has a text input to answer your questions before approving. Don't pretend certainty you don't have; flagged questions are how the user tells you what they care about. After calling submit_plan, STOP \u2014 don't call any more tools, wait for the user's verdict.
+
+# Plan mode (/plan)
+
+The user can ALSO enter "plan mode" via /plan, which is a stronger, explicit constraint:
+- Write tools (edit_file, write_file, create_directory, move_file) and non-allowlisted run_command calls are BOUNCED at dispatch \u2014 you'll get a tool result like "unavailable in plan mode". Don't retry them.
+- Read tools (read_file, list_directory, search_files, directory_tree, get_file_info) and allowlisted read-only / test shell commands still work \u2014 use them to investigate.
+- You MUST call submit_plan before anything will execute. Approve exits plan mode; Refine stays in; Cancel exits without implementing.
+
+
 # When to edit vs. when to explore
 
 Only propose edits when the user explicitly asks you to change, fix, add, remove, refactor, or write something. Do NOT propose edits when the user asks you to:
@@ -3916,9 +4520,13 @@ Rules:
 - Do NOT use write_file to change existing files \u2014 the user reviews your edits as SEARCH/REPLACE. write_file is only for files you explicitly want to overwrite wholesale (rare).
 - Paths are relative to the working directory. Don't use absolute paths.
 
+# Trust what you already know
+
+Before exploring the filesystem to answer a factual question, check whether the answer is already in context: the user's current message, earlier turns in this conversation (including prior tool results from \`remember\`), and the pinned memory blocks at the top of this prompt. When the user has stated a fact or you have remembered one, it outranks what the files say \u2014 don't re-derive from code what the user already told you. Explore when you genuinely don't know.
+
 # Exploration
 
-- Avoid listing or reading inside these common dependency / build directories unless the user explicitly asks about them: node_modules, dist, build, out, .next, .nuxt, .svelte-kit, .git, .venv, venv, __pycache__, target, coverage, .turbo, .cache. They're expensive and usually irrelevant.
+- Skip dependency, build, and VCS directories unless the user explicitly asks. The pinned .gitignore block (if any, below) is your authoritative denylist.
 - Prefer search_files / grep over list_directory when you know roughly what you're looking for \u2014 it saves context and avoids enumerating huge trees.
 
 # Style
@@ -3928,12 +4536,12 @@ Rules:
 - If you need to explore first (list / grep / read), do it with tool calls before writing any prose \u2014 silence while exploring is fine.
 `;
 function codeSystemPrompt(rootDir) {
-  const withMemory = applyProjectMemory(CODE_SYSTEM_PROMPT, rootDir);
-  const gitignorePath = join4(rootDir, ".gitignore");
-  if (!existsSync4(gitignorePath)) return withMemory;
+  const withMemory = applyMemoryStack(CODE_SYSTEM_PROMPT, rootDir);
+  const gitignorePath = join5(rootDir, ".gitignore");
+  if (!existsSync6(gitignorePath)) return withMemory;
   let content;
   try {
-    content = readFileSync6(gitignorePath, "utf8");
+    content = readFileSync7(gitignorePath, "utf8");
   } catch {
     return withMemory;
   }
@@ -3953,15 +4561,15 @@ ${truncated}
 }
 
 // src/config.ts
-import { chmodSync as chmodSync2, mkdirSync as mkdirSync3, readFileSync as readFileSync7, writeFileSync as writeFileSync3 } from "fs";
-import { homedir as homedir2 } from "os";
-import { dirname as dirname4, join as join5 } from "path";
+import { chmodSync as chmodSync2, mkdirSync as mkdirSync4, readFileSync as readFileSync8, writeFileSync as writeFileSync4 } from "fs";
+import { homedir as homedir3 } from "os";
+import { dirname as dirname4, join as join6 } from "path";
 function defaultConfigPath() {
-  return join5(homedir2(), ".reasonix", "config.json");
+  return join6(homedir3(), ".reasonix", "config.json");
 }
 function readConfig(path = defaultConfigPath()) {
   try {
-    const raw = readFileSync7(path, "utf8");
+    const raw = readFileSync8(path, "utf8");
     const parsed = JSON.parse(raw);
     if (parsed && typeof parsed === "object") return parsed;
   } catch {
@@ -3969,8 +4577,8 @@ function readConfig(path = defaultConfigPath()) {
   return {};
 }
 function writeConfig(cfg, path = defaultConfigPath()) {
-  mkdirSync3(dirname4(path), { recursive: true });
-  writeFileSync3(path, JSON.stringify(cfg, null, 2), "utf8");
+  mkdirSync4(dirname4(path), { recursive: true });
+  writeFileSync4(path, JSON.stringify(cfg, null, 2), "utf8");
   try {
     chmodSync2(path, 384);
   } catch {
@@ -3996,7 +4604,7 @@ function redactKey(key) {
 }
 
 // src/index.ts
-var VERSION = "0.4.17";
+var VERSION = "0.4.20";
 export {
   AppendOnlyLog,
   CODE_SYSTEM_PROMPT,
@@ -4005,16 +4613,21 @@ export {
   DeepSeekClient,
   ImmutablePrefix,
   MCP_PROTOCOL_VERSION,
+  MEMORY_INDEX_FILE,
+  MEMORY_INDEX_MAX_CHARS,
   McpClient,
+  MemoryStore,
   NeedsConfirmationError,
   PROJECT_MEMORY_FILE,
   PROJECT_MEMORY_MAX_CHARS,
+  PlanProposedError,
   SessionStats,
   SseTransport,
   StdioTransport,
   StormBreaker,
   ToolCallRepair,
   ToolRegistry,
+  USER_MEMORY_DIR,
   Usage,
   VERSION,
   VolatileScratch,
@@ -4023,7 +4636,9 @@ export {
   appendSessionMessage,
   applyEditBlock,
   applyEditBlocks,
+  applyMemoryStack,
   applyProjectMemory,
+  applyUserMemory,
   bridgeMcpTools,
   claudeEquivalentCost,
   codeSystemPrompt,
@@ -4061,21 +4676,28 @@ export {
   parseMcpSpec,
   parseMojeekResults,
   parseTranscript,
+  prepareSpawn,
+  projectHash,
+  quoteForCmdExe,
   readConfig,
   readProjectMemory,
   readTranscript,
   recordFromLoopEvent,
   redactKey,
   registerFilesystemTools,
+  registerMemoryTools,
+  registerPlanTool,
   registerShellTools,
   registerWebTools,
   renderMarkdown as renderDiffMarkdown,
   renderSummaryTable as renderDiffSummary,
   repairTruncatedJson,
   replayFromFile,
+  resolveExecutable,
   restoreSnapshots,
   runBranches,
   runCommand,
+  sanitizeMemoryName,
   sanitizeName as sanitizeSessionName,
   saveApiKey,
   scavengeToolCalls,