reasonix 0.4.23 → 0.4.26

package/dist/index.js

@@ -1814,6 +1814,10 @@ var CacheFirstLoop = class {
           usage = resp.usage;
         }
       } catch (err) {
+        if (signal.aborted) {
+          yield { turn: this._turn, role: "done", content: "" };
+          return;
+        }
         yield {
           turn: this._turn,
           role: "error",
@@ -2215,9 +2219,11 @@ function isValidSkillName(name) {
 var SkillStore = class {
   homeDir;
   projectRoot;
+  disableBuiltins;
   constructor(opts = {}) {
     this.homeDir = opts.homeDir ?? homedir3();
     this.projectRoot = opts.projectRoot ? resolve(opts.projectRoot) : void 0;
+    this.disableBuiltins = opts.disableBuiltins === true;
   }
   /** True iff this store was configured with a project root. */
   hasProjectScope() {
@@ -2241,8 +2247,8 @@ var SkillStore = class {
   }
   /**
    * List every skill visible to this store. On name collisions the
-   * higher-priority root (project over global) wins. Sorted by name
-   * for stable prefix hashing.
+   * higher-priority root (project over global over builtin) wins.
+   * Sorted by name for stable prefix hashing.
    */
   list() {
     const byName = /* @__PURE__ */ new Map();
@@ -2260,6 +2266,11 @@ var SkillStore = class {
         if (!byName.has(skill.name)) byName.set(skill.name, skill);
       }
     }
+    if (!this.disableBuiltins) {
+      for (const skill of BUILTIN_SKILLS) {
+        if (!byName.has(skill.name)) byName.set(skill.name, skill);
+      }
+    }
     return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
   }
   /** Resolve one skill by name. Returns `null` if not found or malformed. */
@@ -2276,6 +2287,11 @@ var SkillStore = class {
         return this.parse(flatCandidate, name, scope);
       }
     }
+    if (!this.disableBuiltins) {
+      for (const skill of BUILTIN_SKILLS) {
+        if (skill.name === name) return skill;
+      }
+    }
     return null;
   }
   readEntry(dir, scope, entry) {
@@ -2307,15 +2323,21 @@ var SkillStore = class {
       body: body.trim(),
       scope,
       path,
-      allowedTools: data["allowed-tools"]
+      allowedTools: data["allowed-tools"],
+      runAs: parseRunAs(data.runAs),
+      model: data.model?.startsWith("deepseek-") ? data.model : void 0
     };
   }
 };
+function parseRunAs(raw) {
+  return raw?.trim() === "subagent" ? "subagent" : "inline";
+}
 function skillIndexLine(s) {
   const safeDesc = s.description.replace(/\n/g, " ").trim();
-  const max = 130 - s.name.length;
+  const marker = s.runAs === "subagent" ? "\u{1F9EC} " : "";
+  const max = 130 - s.name.length - marker.length;
   const clipped = safeDesc.length > max ? `${safeDesc.slice(0, Math.max(1, max - 1))}\u2026` : safeDesc;
-  return clipped ? `- ${s.name} \u2014 ${clipped}` : `- ${s.name}`;
+  return clipped ? `- ${marker}${s.name} \u2014 ${clipped}` : `- ${marker}${s.name}`;
 }
 function applySkillsIndex(basePrompt, opts = {}) {
   const store = new SkillStore(opts);
@@ -2328,15 +2350,78 @@ function applySkillsIndex(basePrompt, opts = {}) {
   return [
     basePrompt,
     "",
-    "# Skills \u2014 user-defined prompt packs",
+    "# Skills \u2014 playbooks you can invoke",
     "",
-    'One-liner index. Each skill is a self-contained instruction block (plus optional tool hints) the user or an earlier session saved. To load the full body, call `run_skill({ name: "<skill-name>" })` \u2014 the body is NOT in this prompt, only the name and description are. The user can also invoke a skill directly as `/skill <name>`.',
+    'One-liner index. Each entry is either a built-in or a user-authored playbook. Call `run_skill({ name: "<skill-name>", arguments: "<task>" })` to invoke one. Skills marked with \u{1F9EC} spawn an **isolated subagent** \u2014 its tool calls and reasoning never enter your context, only its final answer does. Use \u{1F9EC} skills for tasks that would otherwise flood your context (deep exploration, multi-step research, anything where you only need the conclusion). Plain skills are inlined: their body becomes a tool result you read and act on directly. The user can also invoke a skill via `/skill <name>`.',
     "",
     "```",
     truncated,
     "```"
   ].join("\n");
 }
+var BUILTIN_EXPLORE_BODY = `You are running as an exploration subagent. Your job is to investigate the codebase the parent agent pointed you at, then return one focused, distilled answer.
+
+How to operate:
+- Use read_file, search_files, search_content, directory_tree, list_directory, get_file_info as your primary tools. Stay read-only.
+- For "find all places that call / reference / use X" questions, use \`search_content\` (content grep) \u2014 NOT \`search_files\` (which only matches file names). This is the most common subagent mistake; using the wrong tool gives empty results and you waste your iter budget chasing a phantom.
+- Cast a wide net first (search_content for symbol references, directory_tree for structure) to map the territory; then read the 3-10 most relevant files in full.
+- Don't read every file \u2014 be selective. Aim for breadth on the first pass, depth only where the question demands it.
+- Stop exploring as soon as you can answer the question. The parent doesn't see your tool calls, so over-exploration is pure waste.
+
+Your final answer:
+- One paragraph (or a few short bullets). Lead with the conclusion.
+- Cite specific file paths + line ranges when they support the answer.
+- If the question can't be answered from what you found, say so plainly and suggest where to look next.
+- No follow-up offers, no "let me know if you need more." The parent will ask again if they need more.
+
+Formatting (rendered in a TUI):
+- Tabular data \u2192 GitHub-Flavored Markdown tables with ASCII pipes (\`| col | col |\` + \`| --- | --- |\`). Never use Unicode box-drawing characters (\u2502 \u2500 \u253C) \u2014 they break word-wrap.
+- Keep table cells short; if a cell needs a paragraph, use bullets below the table instead.
+- Code, file paths with line ranges, and shell commands \u2192 fenced code blocks (\`\`\`).
+- NEVER draw decorative frames around code or text with \`\u250C\u2500\u2500\u2510 \u2502 \u2514\u2500\u2500\u2518\` box-drawing characters. Use plain code blocks; the renderer adds its own border.
+- For flow charts: use a bullet list with \`\u2192\` or \`\u2193\` between steps, not ASCII boxes-and-arrows.
+
+The 'task' the parent gave you is the question you must answer. Treat any other reading of it as scope creep.`;
+var BUILTIN_RESEARCH_BODY = `You are running as a research subagent. Your job is to gather information from code AND the web, synthesize it, and return one focused conclusion.
+
+How to operate:
+- Combine code reading (read_file, search_files) with web tools (web_search, web_fetch) as appropriate to the question.
+- For "how does X work" / "is Y supported" questions: web first to find the canonical reference, then verify against the local code.
+- For "what's our policy on Z" / "where do we use Q": local code first, web only if you need to compare against external standards.
+- Cap yourself at ~10 tool calls. If you can't converge in 10, return what you have plus a note about what's missing.
+
+Your final answer:
+- One paragraph (or short bullets). Lead with the conclusion.
+- Cite both code (file:line) AND web sources (URL) when they back the answer.
+- Distinguish "I verified this in code" from "I read this on a docs page" \u2014 the parent will trust the former more.
+- If the answer is uncertain, say so. Don't invent confidence.
+
+Formatting (rendered in a TUI):
+- Tabular data \u2192 GitHub-Flavored Markdown tables with ASCII pipes (\`| col | col |\` + \`| --- | --- |\`). Never use Unicode box-drawing characters (\u2502 \u2500 \u253C) \u2014 they break word-wrap.
+- Keep table cells short; if a cell needs a paragraph, use bullets below the table instead.
+- Code, file paths with line ranges, and shell commands \u2192 fenced code blocks (\`\`\`).
+- NEVER draw decorative frames around code or text with \`\u250C\u2500\u2500\u2510 \u2502 \u2514\u2500\u2500\u2518\` box-drawing characters. Use plain code blocks; the renderer adds its own border.
+- For flow charts: use a bullet list with \`\u2192\` or \`\u2193\` between steps, not ASCII boxes-and-arrows.
+
+The 'task' the parent gave you is the research question. Stay on it.`;
+var BUILTIN_SKILLS = Object.freeze([
+  Object.freeze({
+    name: "explore",
+    description: "Explore the codebase in an isolated subagent \u2014 wide-net read-only investigation that returns one distilled answer. Best for: 'find all places that...', 'how does X work across the project', 'survey the code for Y'.",
+    body: BUILTIN_EXPLORE_BODY,
+    scope: "builtin",
+    path: "(builtin)",
+    runAs: "subagent"
+  }),
+  Object.freeze({
+    name: "research",
+    description: "Research a question by combining web search + code reading in an isolated subagent. Best for: 'is X feature supported by lib Y', 'what's the canonical way to do Z', 'compare our impl against the spec'.",
+    body: BUILTIN_RESEARCH_BODY,
+    scope: "builtin",
+    path: "(builtin)",
+    runAs: "subagent"
+  })
+]);
 
 // src/user-memory.ts
 var USER_MEMORY_DIR = "memory";
@@ -2618,6 +2703,74 @@ import { promises as fs } from "fs";
 import * as pathMod from "path";
 var DEFAULT_MAX_READ_BYTES = 2 * 1024 * 1024;
 var DEFAULT_MAX_LIST_BYTES = 256 * 1024;
+var SKIP_DIR_NAMES = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".git",
+  ".hg",
+  ".svn",
+  "dist",
+  "build",
+  "out",
+  ".next",
+  ".nuxt",
+  "target",
+  // Rust / Java
+  ".venv",
+  "venv",
+  "__pycache__",
+  ".pytest_cache",
+  ".mypy_cache",
+  ".cache",
+  "coverage"
+]);
+var BINARY_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".gif",
+  ".bmp",
+  ".ico",
+  ".webp",
+  ".tiff",
+  ".pdf",
+  ".zip",
+  ".tar",
+  ".gz",
+  ".bz2",
+  ".xz",
+  ".7z",
+  ".rar",
+  ".exe",
+  ".dll",
+  ".so",
+  ".dylib",
+  ".bin",
+  ".class",
+  ".jar",
+  ".war",
+  ".o",
+  ".obj",
+  ".lib",
+  ".a",
+  ".woff",
+  ".woff2",
+  ".ttf",
+  ".otf",
+  ".eot",
+  ".mp3",
+  ".mp4",
+  ".mov",
+  ".avi",
+  ".webm",
+  ".wasm",
+  ".pyc",
+  ".pyo"
+]);
+function isLikelyBinaryByName(name) {
+  const dot = name.lastIndexOf(".");
+  if (dot < 0) return false;
+  return BINARY_EXTENSIONS.has(name.slice(dot).toLowerCase());
+}
 function registerFilesystemTools(registry, opts) {
   const rootDir = pathMod.resolve(opts.rootDir);
   const allowWriting = opts.allowWriting !== false;
@@ -2627,7 +2780,12 @@ function registerFilesystemTools(registry, opts) {
     if (typeof raw !== "string" || raw.length === 0) {
       throw new Error("path must be a non-empty string");
     }
-    const resolved = pathMod.resolve(rootDir, raw);
+    let normalized = raw;
+    while (normalized.startsWith("/") || normalized.startsWith("\\")) {
+      normalized = normalized.slice(1);
+    }
+    if (normalized.length === 0) normalized = ".";
+    const resolved = pathMod.resolve(rootDir, normalized);
     const normRoot = pathMod.resolve(rootDir);
     const rel = pathMod.relative(normRoot, resolved);
     if (rel.startsWith("..") || pathMod.isAbsolute(rel)) {
@@ -2793,6 +2951,114 @@ function registerFilesystemTools(registry, opts) {
       return matches.length === 0 ? "(no matches)" : matches.join("\n");
     }
   });
+  registry.register({
+    name: "search_content",
+    description: "Recursively grep file CONTENTS for a substring or regex. This is the right tool for 'find all places that call X', 'where is Y referenced', 'what files contain Z'. Different from search_files (which matches FILE NAMES). Returns one match per line in 'path:line: text' format. Skips dependency / VCS / build directories (node_modules, .git, dist, build, .next, target, .venv) and binary files by default.",
+    readOnly: true,
+    parameters: {
+      type: "object",
+      properties: {
+        pattern: {
+          type: "string",
+          description: "Substring (or regex) to search file contents for."
+        },
+        path: {
+          type: "string",
+          description: "Directory to start the search at (default: sandbox root)."
+        },
+        glob: {
+          type: "string",
+          description: "Optional file-name suffix or substring filter. Examples: '.ts' (only TypeScript), 'test' (any file with 'test' in the name). Reduces noise when you know the file shape."
+        },
+        case_sensitive: {
+          type: "boolean",
+          description: "When true, match case exactly. Default false (case-insensitive)."
+        },
+        include_deps: {
+          type: "boolean",
+          description: "When true, also search inside node_modules / .git / dist / build / etc. Off by default \u2014 most exploration questions are about the user's own code."
+        }
+      },
+      required: ["pattern"]
+    },
+    fn: async (args) => {
+      const startAbs = safePath(args.path ?? ".");
+      const caseSensitive = args.case_sensitive === true;
+      const includeDeps = args.include_deps === true;
+      const nameFilter = typeof args.glob === "string" ? args.glob.toLowerCase() : null;
+      let re = null;
+      try {
+        re = new RegExp(args.pattern, caseSensitive ? "" : "i");
+      } catch {
+        re = null;
+      }
+      const needle = caseSensitive ? args.pattern : args.pattern.toLowerCase();
+      const matches = [];
+      let totalBytes = 0;
+      let scanned = 0;
+      let truncated = false;
+      const walk2 = async (dir) => {
+        if (truncated) return;
+        let entries;
+        try {
+          entries = await fs.readdir(dir, { withFileTypes: true });
+        } catch {
+          return;
+        }
+        for (const e of entries) {
+          if (truncated) return;
+          if (e.isDirectory()) {
+            if (!includeDeps && SKIP_DIR_NAMES.has(e.name)) continue;
+            await walk2(pathMod.join(dir, e.name));
+            continue;
+          }
+          if (!e.isFile()) continue;
+          if (nameFilter && !e.name.toLowerCase().includes(nameFilter)) continue;
+          if (isLikelyBinaryByName(e.name)) continue;
+          const full = pathMod.join(dir, e.name);
+          let stat;
+          try {
+            stat = await fs.stat(full);
+          } catch {
+            continue;
+          }
+          if (stat.size > 2 * 1024 * 1024) continue;
+          let raw;
+          try {
+            raw = await fs.readFile(full);
+          } catch {
+            continue;
+          }
+          const firstNul = raw.indexOf(0);
+          if (firstNul !== -1 && firstNul < 8 * 1024) continue;
+          const text = raw.toString("utf8");
+          const rel = pathMod.relative(rootDir, full);
+          const lines = text.split(/\r?\n/);
+          for (let li = 0; li < lines.length; li++) {
+            const line = lines[li];
+            const lineForCheck = caseSensitive ? line : line.toLowerCase();
+            const hit = re ? re.test(line) : lineForCheck.includes(needle);
+            if (!hit) continue;
+            const display = line.length > 200 ? `${line.slice(0, 200)}\u2026` : line;
+            const out = `${rel}:${li + 1}: ${display}`;
+            if (totalBytes + out.length + 1 > maxListBytes) {
+              matches.push(`[\u2026 truncated at ${maxListBytes} bytes \u2014 refine pattern or path \u2026]`);
+              truncated = true;
+              return;
+            }
+            matches.push(out);
+            totalBytes += out.length + 1;
+          }
+          scanned++;
+        }
+      };
+      await walk2(startAbs);
+      if (matches.length === 0) {
+        return scanned === 0 ? "(no files scanned \u2014 path empty or all files filtered out)" : `(no matches across ${scanned} file${scanned === 1 ? "" : "s"})`;
+      }
+      return matches.join("\n");
+    }
+  });
   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.",
@@ -3119,6 +3385,195 @@ function registerPlanTool(registry, opts = {}) {
   return registry;
 }
 
+// src/tools/subagent.ts
+var DEFAULT_SUBAGENT_SYSTEM = `You are a Reasonix subagent. The parent agent spawned you to handle one focused subtask, then return.
+
+Rules:
+- Stay on the task you were given. Do not expand scope.
+- Use tools as needed. You share the parent's sandbox + safety rules.
+- When you're done, your final assistant message is the only thing the parent will see \u2014 make it complete and self-contained. No follow-up offers, no questions, no "let me know if you need more."
+- Prefer one clear, distilled answer over a long log of what you tried.
+
+Formatting rules (the parent renders your reply in a TUI with a real markdown renderer):
+- For tabular data use GitHub-Flavored Markdown tables with ASCII pipes: \`| col | col |\` headers, \`| --- | --- |\` separator. NEVER draw tables with Unicode box-drawing characters (\u2502 \u2500 \u253C \u250C \u2510 \u2514 \u2518 \u251C \u2524). They look intentional but break terminal word-wrap and produce garbled output.
+- Keep table cells short \u2014 one short phrase per cell, not multi-line paragraphs. If a description doesn't fit in ~40 chars, use bullets below the table instead.
+- Use fenced code blocks (\`\`\`) for any code, file paths with line ranges, or shell commands.
+- NEVER draw decorative frames around content with \`\u250C\u2500\u2500\u2510 \u2502 \u2514\u2500\u2500\u2518\` box-drawing characters. The renderer handles code blocks and headings on its own \u2014 extra ASCII art adds noise without value and breaks at narrow terminal widths.
+- For flow charts and diagrams: use a markdown bullet list with \`\u2192\` or \`\u2193\` between steps. Don't try to draw boxes-and-arrows in ASCII; it never survives word-wrap.`;
+var DEFAULT_MAX_RESULT_CHARS2 = 8e3;
+var DEFAULT_MAX_ITERS = 16;
+var DEFAULT_SUBAGENT_MODEL = "deepseek-chat";
+var SUBAGENT_TOOL_NAME = "spawn_subagent";
+var NEVER_INHERITED_TOOLS = /* @__PURE__ */ new Set([SUBAGENT_TOOL_NAME, "submit_plan"]);
+async function spawnSubagent(opts) {
+  const model = opts.model ?? DEFAULT_SUBAGENT_MODEL;
+  const maxToolIters = opts.maxToolIters ?? DEFAULT_MAX_ITERS;
+  const maxResultChars = opts.maxResultChars ?? DEFAULT_MAX_RESULT_CHARS2;
+  const sink = opts.sink;
+  const startedAt = Date.now();
+  const taskPreview = opts.task.length > 30 ? `${opts.task.slice(0, 30)}\u2026` : opts.task;
+  sink?.current?.({
+    kind: "start",
+    task: taskPreview,
+    iter: 0,
+    elapsedMs: 0
+  });
+  const childTools = forkRegistryExcluding(opts.parentRegistry, NEVER_INHERITED_TOOLS);
+  const childPrefix = new ImmutablePrefix({
+    system: opts.system,
+    toolSpecs: childTools.specs()
+  });
+  const childLoop = new CacheFirstLoop({
+    client: opts.client,
+    prefix: childPrefix,
+    tools: childTools,
+    model,
+    maxToolIters,
+    hooks: [],
+    stream: false
+  });
+  const onParentAbort = () => childLoop.abort();
+  opts.parentSignal?.addEventListener("abort", onParentAbort, { once: true });
+  let final = "";
+  let errorMessage;
+  let toolIter = 0;
+  try {
+    for await (const ev of childLoop.step(opts.task)) {
+      if (ev.role === "tool") {
+        toolIter++;
+        sink?.current?.({
+          kind: "progress",
+          task: taskPreview,
+          iter: toolIter,
+          elapsedMs: Date.now() - startedAt
+        });
+      }
+      if (ev.role === "assistant_final") {
+        final = ev.content ?? "";
+      }
+      if (ev.role === "error") {
+        errorMessage = ev.error ?? "subagent error";
+      }
+    }
+  } catch (err) {
+    errorMessage = err.message;
+  } finally {
+    opts.parentSignal?.removeEventListener("abort", onParentAbort);
+  }
+  if (!errorMessage && !final) {
+    errorMessage = opts.parentSignal?.aborted ? "subagent aborted before producing an answer" : "subagent ended without producing an answer";
+  }
+  const elapsedMs = Date.now() - startedAt;
+  const turns = childLoop.stats.turns.length;
+  const costUsd2 = childLoop.stats.totalCost;
+  const truncated = final.length > maxResultChars ? `${final.slice(0, maxResultChars)}
+
+[\u2026truncated ${final.length - maxResultChars} chars; ask the subagent for a tighter summary if you need more.]` : final;
+  sink?.current?.({
+    kind: "end",
+    task: taskPreview,
+    iter: toolIter,
+    elapsedMs,
+    summary: errorMessage ? void 0 : truncated.slice(0, 120),
+    error: errorMessage,
+    turns
+  });
+  return {
+    success: !errorMessage,
+    output: errorMessage ? "" : truncated,
+    error: errorMessage,
+    turns,
+    toolIters: toolIter,
+    elapsedMs,
+    costUsd: costUsd2
+  };
+}
+function formatSubagentResult(r) {
+  if (!r.success) {
+    return JSON.stringify({
+      success: false,
+      error: r.error ?? "unknown subagent error",
+      turns: r.turns,
+      tool_iters: r.toolIters,
+      elapsed_ms: r.elapsedMs
+    });
+  }
+  return JSON.stringify({
+    success: true,
+    output: r.output,
+    turns: r.turns,
+    tool_iters: r.toolIters,
+    elapsed_ms: r.elapsedMs,
+    cost_usd: r.costUsd
+  });
+}
+function registerSubagentTool(parentRegistry, opts) {
+  const baseSystem = opts.defaultSystem ?? DEFAULT_SUBAGENT_SYSTEM;
+  const defaultSystem = opts.projectRoot ? applyProjectMemory(baseSystem, opts.projectRoot) : baseSystem;
+  const defaultModel = opts.defaultModel ?? DEFAULT_SUBAGENT_MODEL;
+  const maxToolIters = opts.maxToolIters ?? DEFAULT_MAX_ITERS;
+  const maxResultChars = opts.maxResultChars ?? DEFAULT_MAX_RESULT_CHARS2;
+  const sink = opts.sink;
+  parentRegistry.register({
+    name: SUBAGENT_TOOL_NAME,
+    description: "Spawn an isolated subagent to handle a self-contained subtask in a fresh context, returning only its final answer. Use for: deep codebase exploration that would flood the main context, multi-step research where you only need the conclusion, or any focused subtask whose intermediate reasoning the user does not need to see. The subagent inherits all your tools (filesystem, shell, web, MCP, etc.) but runs in its own isolated message log \u2014 its tool calls and reasoning never enter your context. Only the final assistant message comes back as this tool's result. Keep tasks focused; the subagent has a stricter iter budget than you do.",
+    parameters: {
+      type: "object",
+      properties: {
+        task: {
+          type: "string",
+          description: "The subtask the subagent should perform. Be specific and self-contained \u2014 the subagent has none of your conversation context, only what you write here."
+        },
+        system: {
+          type: "string",
+          description: "Optional override for the subagent's system prompt. The default tells it to stay focused and return a concise answer; override only when the subtask needs a specialized persona."
+        },
+        model: {
+          type: "string",
+          enum: ["deepseek-chat", "deepseek-reasoner"],
+          description: "Which DeepSeek model the subagent runs on. 'deepseek-chat' (V3) is the default \u2014 fast and cheap. Use 'deepseek-reasoner' (R1) only when the subtask genuinely needs planning or multi-step reasoning; it is roughly 5-10x more expensive."
+        }
+      },
+      required: ["task"]
+    },
+    fn: async (args, ctx) => {
+      const task = typeof args.task === "string" ? args.task.trim() : "";
+      if (!task) {
+        return JSON.stringify({
+          error: "spawn_subagent requires a non-empty 'task' argument."
+        });
+      }
+      const system = typeof args.system === "string" && args.system.trim().length > 0 ? args.system.trim() : defaultSystem;
+      const model = typeof args.model === "string" && args.model.startsWith("deepseek-") ? args.model : defaultModel;
+      const result = await spawnSubagent({
+        client: opts.client,
+        parentRegistry,
+        system,
+        task,
+        model,
+        maxToolIters,
+        maxResultChars,
+        sink,
+        parentSignal: ctx?.signal
+      });
+      return formatSubagentResult(result);
+    }
+  });
+  return parentRegistry;
+}
+function forkRegistryExcluding(parent, exclude) {
+  const child = new ToolRegistry();
+  for (const spec of parent.specs()) {
+    const name = spec.function.name;
+    if (exclude.has(name)) continue;
+    const def = parent.get(name);
+    if (!def) continue;
+    child.register(def);
+  }
+  if (parent.planMode) child.setPlanMode(true);
+  return child;
+}
+
 // src/tools/shell.ts
 import { spawn as spawn2 } from "child_process";
 import { existsSync as existsSync6, statSync as statSync3 } from "fs";
@@ -3316,7 +3771,7 @@ function prepareSpawn(argv, opts = {}) {
     const cmdline = [resolved, ...tail].map(quoteForCmdExe).join(" ");
     return {
       bin: "cmd.exe",
-      args: ["/d", "/s", "/c", cmdline],
+      args: ["/d", "/s", "/c", withUtf8Codepage(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
@@ -3328,12 +3783,36 @@ function prepareSpawn(argv, opts = {}) {
     const cmdline = [head, ...tail].map(quoteForCmdExe).join(" ");
     return {
       bin: "cmd.exe",
-      args: ["/d", "/s", "/c", cmdline],
+      args: ["/d", "/s", "/c", withUtf8Codepage(cmdline)],
       spawnOverrides: { windowsVerbatimArguments: true }
     };
   }
+  if (isPowerShellExe(resolved)) {
+    const patched = injectPowerShellUtf8(tail);
+    if (patched) {
+      return { bin: resolved, args: patched, spawnOverrides: {} };
+    }
+  }
   return { bin: resolved, args: [...tail], spawnOverrides: {} };
 }
+function isPowerShellExe(resolved) {
+  return /(?:^|[\\/])(?:powershell|pwsh)(?:\.exe)?$/i.test(resolved);
+}
+function injectPowerShellUtf8(args) {
+  const prelude = "[Console]::OutputEncoding=[System.Text.Encoding]::UTF8;$OutputEncoding=[System.Text.Encoding]::UTF8;";
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i] ?? "";
+    if (/^-(?:Command|c)$/i.test(a) && i + 1 < args.length) {
+      const out = [...args];
+      out[i + 1] = `${prelude}${args[i + 1] ?? ""}`;
+      return out;
+    }
+  }
+  return null;
+}
+function withUtf8Codepage(cmdline) {
+  return `chcp 65001 >nul & ${cmdline}`;
+}
 function isBareWindowsName(s) {
   if (!s) return false;
   if (s.includes("/") || s.includes("\\")) return false;
@@ -4882,6 +5361,26 @@ The user can ALSO enter "plan mode" via /plan, which is a stronger, explicit con
 - You MUST call submit_plan before anything will execute. Approve exits plan mode; Refine stays in; Cancel exits without implementing.
 
 
+# Delegating to subagents via Skills (\u{1F9EC})
+
+The pinned Skills index below lists playbooks you can invoke with \`run_skill\`. Skills marked with **\u{1F9EC}** spawn an **isolated subagent** \u2014 a fresh child loop that runs the playbook in its own context and returns only the final answer. The subagent's tool calls and reasoning never enter your context, so \u{1F9EC} skills are how you keep the main session lean.
+
+Two built-ins ship by default:
+- **\u{1F9EC} explore** \u2014 read-only investigation across the codebase. Use when the user says things like "find all places that...", "how does X work across the project", "survey the code for Y". Pass \`arguments\` describing the concrete question.
+- **\u{1F9EC} research** \u2014 combines web search + code reading. Use for "is X supported by lib Y", "what's the canonical way to Z", "compare our impl to the spec".
+
+When to delegate (call \`run_skill\` with a \u{1F9EC} skill):
+- The task would otherwise need >5 file reads or searches.
+- You only need the conclusion, not the exploration trail.
+- The work is self-contained (you can describe it in one paragraph).
+
+When NOT to delegate:
+- Direct, narrow questions answerable in 1-2 tool calls \u2014 just do them.
+- Anything where you need to track intermediate results yourself (planning, multi-step edits).
+- Anything that requires user interaction (subagents can't submit plans or ask you for clarification).
+
+Always pass a clear, self-contained \`arguments\` \u2014 that text is the **only** context the subagent gets.
+
 # 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:
@@ -4923,13 +5422,21 @@ Before exploring the filesystem to answer a factual question, check whether the
 # Exploration
 
 - 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.
+- Prefer \`search_files\` over \`list_directory\` when you know roughly what you're looking for \u2014 it saves context and avoids enumerating huge trees. Note: \`search_files\` matches file NAMES; for searching file CONTENTS use \`search_content\`.
+- Available exploration tools: \`read_file\`, \`list_directory\`, \`directory_tree\`, \`search_files\` (filename match), \`search_content\` (content grep \u2014 use for "where is X called", "find all references to Y"), \`get_file_info\`. Don't call \`grep\` or other tools that aren't in this list \u2014 they don't exist as functions.
+
+# Path conventions
+
+Two different rules depending on which tool:
+
+- **Filesystem tools** (\`read_file\`, \`list_directory\`, \`search_files\`, \`edit_file\`, etc.): paths are sandbox-relative. \`/\` means the project root, \`/src/foo.ts\` means \`<project>/src/foo.ts\`. Both relative (\`src/foo.ts\`) and POSIX-absolute (\`/src/foo.ts\`) forms work.
+- **\`run_command\`**: the command runs in a real OS shell with cwd pinned to the project root. Paths inside the shell command are interpreted by THAT shell, not by us. **Never use leading \`/\` in run_command arguments** \u2014 Windows treats \`/tests\` as drive-root \`F:\\tests\` (non-existent), POSIX shells treat it as filesystem root. Use plain relative paths (\`tests\`, \`./tests\`, \`src/loop.ts\`) instead.
 
 # Style
 
 - Show edits; don't narrate them in prose. "Here's the fix:" is enough.
 - One short paragraph explaining *why*, then the blocks.
-- If you need to explore first (list / grep / read), do it with tool calls before writing any prose \u2014 silence while exploring is fine.
+- If you need to explore first (list / read / search), do it with tool calls before writing any prose \u2014 silence while exploring is fine.
 `;
 function codeSystemPrompt(rootDir) {
   const withMemory = applyMemoryStack(CODE_SYSTEM_PROMPT, rootDir);
@@ -5099,6 +5606,132 @@ function isNpxInstall() {
   if (ua.includes("npx/")) return true;
   return false;
 }
+
+// src/usage.ts
+import { appendFileSync as appendFileSync2, existsSync as existsSync10, mkdirSync as mkdirSync6, readFileSync as readFileSync12, statSync as statSync4 } from "fs";
+import { homedir as homedir7 } from "os";
+import { dirname as dirname6, join as join10 } from "path";
+function defaultUsageLogPath(homeDirOverride) {
+  return join10(homeDirOverride ?? homedir7(), ".reasonix", "usage.jsonl");
+}
+function appendUsage(input) {
+  const record = {
+    ts: input.now ?? Date.now(),
+    session: input.session,
+    model: input.model,
+    promptTokens: input.usage.promptTokens,
+    completionTokens: input.usage.completionTokens,
+    cacheHitTokens: input.usage.promptCacheHitTokens,
+    cacheMissTokens: input.usage.promptCacheMissTokens,
+    costUsd: costUsd(input.model, input.usage),
+    claudeEquivUsd: claudeEquivalentCost(input.usage)
+  };
+  const path = input.path ?? defaultUsageLogPath();
+  try {
+    mkdirSync6(dirname6(path), { recursive: true });
+    appendFileSync2(path, `${JSON.stringify(record)}
+`, "utf8");
+  } catch {
+  }
+  return record;
+}
+function readUsageLog(path = defaultUsageLogPath()) {
+  if (!existsSync10(path)) return [];
+  let raw;
+  try {
+    raw = readFileSync12(path, "utf8");
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    try {
+      const rec = JSON.parse(line);
+      if (isValidRecord(rec)) out.push(rec);
+    } catch {
+    }
+  }
+  return out;
+}
+function isValidRecord(rec) {
+  if (!rec || typeof rec !== "object") return false;
+  const r = rec;
+  return typeof r.ts === "number" && typeof r.model === "string" && typeof r.promptTokens === "number" && typeof r.completionTokens === "number" && typeof r.cacheHitTokens === "number" && typeof r.cacheMissTokens === "number" && typeof r.costUsd === "number" && typeof r.claudeEquivUsd === "number";
+}
+function bucketCacheHitRatio(b) {
+  const denom = b.cacheHitTokens + b.cacheMissTokens;
+  return denom > 0 ? b.cacheHitTokens / denom : 0;
+}
+function bucketSavingsFraction(b) {
+  return b.claudeEquivUsd > 0 ? 1 - b.costUsd / b.claudeEquivUsd : 0;
+}
+function emptyBucket(label, since) {
+  return {
+    label,
+    since,
+    turns: 0,
+    promptTokens: 0,
+    completionTokens: 0,
+    cacheHitTokens: 0,
+    cacheMissTokens: 0,
+    costUsd: 0,
+    claudeEquivUsd: 0
+  };
+}
+function addToBucket(b, r) {
+  b.turns += 1;
+  b.promptTokens += r.promptTokens;
+  b.completionTokens += r.completionTokens;
+  b.cacheHitTokens += r.cacheHitTokens;
+  b.cacheMissTokens += r.cacheMissTokens;
+  b.costUsd += r.costUsd;
+  b.claudeEquivUsd += r.claudeEquivUsd;
+}
+function aggregateUsage(records, opts = {}) {
+  const now = opts.now ?? Date.now();
+  const day = 24 * 60 * 60 * 1e3;
+  const today = emptyBucket("today", now - day);
+  const week = emptyBucket("week", now - 7 * day);
+  const month = emptyBucket("month", now - 30 * day);
+  const all = emptyBucket("all-time", 0);
+  const modelCounts = /* @__PURE__ */ new Map();
+  const sessionCounts = /* @__PURE__ */ new Map();
+  let firstSeen = null;
+  let lastSeen = null;
+  for (const r of records) {
+    addToBucket(all, r);
+    if (r.ts >= today.since) addToBucket(today, r);
+    if (r.ts >= week.since) addToBucket(week, r);
+    if (r.ts >= month.since) addToBucket(month, r);
+    modelCounts.set(r.model, (modelCounts.get(r.model) ?? 0) + 1);
+    const sessKey = r.session ?? "(ephemeral)";
+    sessionCounts.set(sessKey, (sessionCounts.get(sessKey) ?? 0) + 1);
+    if (firstSeen === null || r.ts < firstSeen) firstSeen = r.ts;
+    if (lastSeen === null || r.ts > lastSeen) lastSeen = r.ts;
+  }
+  const byModel = Array.from(modelCounts.entries()).map(([model, turns]) => ({ model, turns })).sort((a, b) => b.turns - a.turns);
+  const bySession = Array.from(sessionCounts.entries()).map(([session, turns]) => ({ session, turns })).sort((a, b) => b.turns - a.turns);
+  return {
+    buckets: [today, week, month, all],
+    byModel,
+    bySession,
+    firstSeen,
+    lastSeen
+  };
+}
+function formatLogSize(path = defaultUsageLogPath()) {
+  if (!existsSync10(path)) return "";
+  try {
+    const s = statSync4(path);
+    const bytes = s.size;
+    if (bytes < 1024) return `${bytes} B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  } catch {
+    return "";
+  }
+}
 export {
   AppendOnlyLog,
   CODE_SYSTEM_PROMPT,
@@ -5131,14 +5764,18 @@ export {
   VERSION,
   VolatileScratch,
   aggregateBranchUsage,
+  aggregateUsage,
   analyzeSchema,
   appendSessionMessage,
+  appendUsage,
   applyEditBlock,
   applyEditBlocks,
   applyMemoryStack,
   applyProjectMemory,
   applyUserMemory,
   bridgeMcpTools,
+  bucketCacheHitRatio,
+  bucketSavingsFraction,
   claudeEquivalentCost,
   codeSystemPrompt,
   compareVersions,
@@ -5147,14 +5784,17 @@ export {
   decideOutcome,
   defaultConfigPath,
   defaultSelector,
+  defaultUsageLogPath,
   deleteSession,
   diffTranscripts,
   emptyPlanState,
   fetchWithRetry,
   flattenMcpResult,
   flattenSchema,
+  forkRegistryExcluding,
   formatCommandResult,
   formatHookOutcomeMessage,
+  formatLogSize,
   formatLoopError,
   formatSearchResults,
   getLatestVersion,
@@ -5162,6 +5802,7 @@ export {
   harvest,
   healLoadedMessages,
   htmlToText,
+  injectPowerShellUtf8,
   inputCostUsd,
   inspectMcpServer,
   isAllowed,
@@ -5190,12 +5831,14 @@ export {
   readConfig,
   readProjectMemory,
   readTranscript,
+  readUsageLog,
   recordFromLoopEvent,
   redactKey,
   registerFilesystemTools,
   registerMemoryTools,
   registerPlanTool,
   registerShellTools,
+  registerSubagentTool,
   registerWebTools,
   renderMarkdown as renderDiffMarkdown,
   renderSummaryTable as renderDiffSummary,
@@ -5219,6 +5862,7 @@ export {
   truncateForModel,
   webFetch,
   webSearch,
+  withUtf8Codepage,
   writeConfig,
   writeMeta,
   writeRecord