agent-sh 0.14.9 → 0.14.11

package/examples/extensions/ash-scheme/index.ts

@@ -5,9 +5,13 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { createRequire } from "node:module";
 import type { AgentContext } from "agent-sh/types";
 import { getSettings } from "agent-sh/settings";
-import lips from "@jcubic/lips";
+// LIPS 1.0's ESM build exposes named exports with no default; older builds (and
+// the CJS interop path) put everything under `default`. Accept both.
+import * as lipsNs from "@jcubic/lips";
+const lips: any = (lipsNs as any).default ?? lipsNs;
 
 type ToolResult = {
   content: string; exitCode: number | null; isError: boolean;
@@ -26,6 +30,8 @@ async function withDisplay(
     title: toolName, toolCallId, kind, rawInput, displayDetail,
   });
   const result = await run();
+  // Stream the result so the TUI's tracked `output` holds it, not just the summary.
+  if (result.content) bus.emit("agent:tool-output-chunk", { toolCallId, chunk: result.content });
   bus.emit("agent:tool-completed", {
     toolCallId,
     exitCode: result.exitCode,
@@ -41,64 +47,16 @@ async function withDisplay(
 // the TUI still renders diffs.
 const HIDDEN_IN_SCHEME_ONLY = ["bash", "pwsh", "read_file", "write_file", "edit_file", "ls", "glob", "grep"];
 
-const { Pair, nil, LSymbol, LNumber, Macro, evaluate: lipsEvaluate } = lips as any;
-
-// LIPS' `define` discards the promise returned by async host bindings.
-// With `(define x (read-file …)) x` the exec() advances before `env.set`
-// fires, so `x` is reported unbound. Reinstall to return the promise.
-function installFixedDefine(env: any): void {
-  const fixed = Macro.defmacro("define", function (this: any, code: any, eval_args: any) {
-    const target = this;
-    if (code.car instanceof Pair && code.car.car instanceof LSymbol) {
-      return new Pair(
-        new LSymbol("define"),
-        new Pair(
-          code.car.car,
-          new Pair(
-            new Pair(new LSymbol("lambda"), new Pair(code.car.cdr, code.cdr)),
-            nil,
-          ),
-        ),
-      );
-    } else if (eval_args.macro_expand) {
-      return;
-    }
-    if (eval_args.dynamic_scope) eval_args.dynamic_scope = target;
-    eval_args.env = target;
-    let value = code.cdr.car;
-    if (value instanceof Pair) {
-      value = lipsEvaluate(value, eval_args);
-    } else if (value instanceof LSymbol) {
-      value = target.get(value);
-    }
-    if (code.car instanceof LSymbol) {
-      const name = code.car;
-      if (value && typeof value.then === "function") {
-        return value.then((v: any) => { target.set(name, v); });
-      }
-      target.set(name, value);
-    }
-  });
-  env.set("define", fixed);
-}
+const { Pair, nil, LSymbol, LNumber, Macro, bootstrap, LString } = lips as any;
 
-// LIPS' `if` is strict-boolean: `(if "hello" …)` errors. R7RS, Racket, Chicken
-// — essentially every Scheme model is trained on — treat any non-#f as true.
-// Reinstall a lenient `if`.
-function installLenientIf(env: any): void {
-  const lenient = new Macro("if", function (this: any, code: any, opts: any) {
-    const target = this;
-    const dynScope = opts.dynamic_scope ? target : undefined;
-    const choose = (cond: any) => {
-      const branch = cond !== false ? code.cdr.car : code.cdr.cdr.car;
-      return lipsEvaluate(branch, { env: target, dynamic_scope: dynScope, error: opts.error });
-    };
-    const condVal = lipsEvaluate(code.car, { env: target, dynamic_scope: dynScope, error: opts.error });
-    if (condVal && typeof condVal.then === "function") return condVal.then(choose);
-    return choose(condVal);
-  });
-  env.set("if", lenient);
-}
+// LIPS 1.0 boxes string literals as LString; unbox to a JS primitive so the gap
+// shims and host bridge (which assume JS strings) operate on them correctly.
+const toJsStr = (x: any): any => (x instanceof LString ? x.toString() : x);
+
+// LIPS 1.0 stores a symbol's name in `__name__`; `.name` is undefined (the 0.x
+// build used `.name`). Read every symbol name through this so both builds work.
+const symName = (x: any): string | undefined =>
+  x instanceof LSymbol ? ((x as any).__name__ ?? (x as any).name) : undefined;
 
 const LOG_PATH = path.join(os.homedir(), ".agent-sh", "scheme-eval.log");
 const SCHEME_DEFINE_DIR = path.join(os.homedir(), ".agent-sh", "scheme-define");
@@ -123,7 +81,7 @@ function installSchemeDefine(
       throw new Error("scheme-define: expected (scheme-define name (args …) \"doc\" body …)");
     }
     const nameSym = code.car;
-    const name = nameSym.name;
+    const name = symName(nameSym)!;
     const argsForm = code.cdr instanceof Pair ? code.cdr.car : nil;
     let rest = code.cdr instanceof Pair ? code.cdr.cdr : nil;
     let doc = "";
@@ -175,7 +133,7 @@ async function loadPersistedDefines(
       const fp = path.join(SCHEME_DEFINE_DIR, f);
       try {
         const src = fs.readFileSync(fp, "utf-8");
-        await (lips as any).exec(src, env);
+        await (lips as any).exec(src, { env });
       } catch (e) {
         logErr("scheme-define load", e, { file: fp });
       }
@@ -266,7 +224,7 @@ function lookup(result: unknown, key: string): unknown {
   let node: any = result;
   while (node && node instanceof Pair) {
     const entry = node.car;
-    if (entry && entry.car && entry.car.name === key) return entry.cdr;
+    if (entry && entry.car && symName(entry.car) === key) return entry.cdr;
     node = node.cdr;
   }
   return undefined;
@@ -310,8 +268,11 @@ function stripPagination(raw: string): string[] {
 
 function format(v: unknown): string {
   if (v === undefined || v === null) return "";
+  if (v instanceof LString) v = v.toString();
   if (typeof v === "string") return JSON.stringify(v);
-  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  // Render JS booleans Scheme-style, matching how #t/#f print inside records.
+  if (typeof v === "boolean") return v ? "#t" : "#f";
+  if (typeof v === "number") return String(v);
   if (v && typeof (v as any).toString === "function") {
     try { return (v as any).toString(); } catch {}
   }
@@ -319,10 +280,9 @@ function format(v: unknown): string {
 }
 
 // ── evaluator ─────────────────────────────────────────────────────
-// LIPS implements string literals via JSON.parse, which rejects backslash
-// escapes outside JSON's tiny set (\" \\ \/ \b \f \n \r \t \uXXXX). Models
-// routinely write \s \w \d etc. in regex strings. Pre-process: promote any
-// invalid \X to \\X so LIPS parses it as a literal backslash + X.
+// LIPS' string lexer accepts only JSON-style escapes (\" \\ \/ \b \f \n \r \t
+// \uXXXX), but models routinely write \s \w \d etc. in regex strings. Promote
+// any other \X to \\X so it parses as a literal backslash + X.
 function preprocessSchemeSource(source: string): string {
   const JSON_ESC = new Set(["\\", "/", '"', "b", "f", "n", "r", "t"]);
   let out = "";
@@ -355,16 +315,16 @@ function preprocessSchemeSource(source: string): string {
       i++;
       continue;
     }
-    // Any other \X — promote so JSON.parse sees \\X → literal
+    // Any other \X — promote to \\X so it parses as a literal backslash
     out += "\\\\" + next;
     i++;
   }
   return out;
 }
 
-// If LIPS reports a JSON-parse failure, localize the invalid escapes so the
-// agent gets actionable line/col info instead of a raw offset. Only triggers
-// when preprocessing didn't catch everything.
+// If LIPS rejects a string literal, localize the invalid escapes so the agent
+// gets actionable line/col info instead of a raw offset. Only triggers when
+// preprocessing didn't catch everything.
 function formatStringEscapeDiagnostic(source: string, baseMsg: string): string {
   const JSON_ESC = new Set(["\\", "/", '"', "b", "f", "n", "r", "t"]);
   let line = 1, col = 1;
@@ -474,30 +434,29 @@ function formatParenDiagnostic(source: string, baseMsg: string): string {
 
 async function evaluate(env: any, source: string, timeoutMs: number) {
   const preprocessed = preprocessSchemeSource(source);
-  // Install a per-eval stdout buffer so (display …) output is captured into
-  // the result instead of vanishing to console.log. Also override `display`
-  // to drop LIPS' string-quoting (its default writes `"hello"` with literal
-  // quote marks; R7RS display should be raw).
-  const prevStdout = (env as any).get("stdout", { throwError: false });
-  const prevDisplay = (env as any).get("display", { throwError: false });
+  // Capture output into the result instead of letting it vanish to console.log.
+  // LIPS 1.0's native display/write resolve the *functions* from the env (the
+  // stdout-port override alone misses them), so shadow each output procedure.
+  const OUTPUT_PROCS = ["stdout", "display", "write", "write-string", "write-char"];
+  const prev: Record<string, any> = {};
+  for (const name of OUTPUT_PROCS) prev[name] = (env as any).get(name, { throwError: false });
   const buf: string[] = [];
-  (env as any).set("stdout", {
-    write: (...args: any[]) => {
-      for (const a of args) buf.push(typeof a === "string" ? a : String(a));
-    },
-  });
-  (env as any).set("display", (...args: any[]) => {
-    const out = args.map((a) => {
-      if (a === null || a === undefined) return "";
-      if (typeof a === "string") return a;
-      if (a && typeof (a as any).toString === "function") return (a as any).toString();
-      return String(a);
-    }).join("");
-    buf.push(out);
+  const raw = (a: any): string => {
+    if (a === null || a === undefined) return "";
+    if (typeof a === "string") return a;
+    if (a && typeof (a as any).toString === "function") return (a as any).toString();
+    return String(a);
+  };
+  (env as any).set("stdout", { write: (...args: any[]) => { for (const a of args) buf.push(raw(a)); } });
+  (env as any).set("display", (...args: any[]) => { buf.push(args.map(raw).join("")); });
+  (env as any).set("write", (...args: any[]) => {
+    buf.push(args.map((a) => (typeof toJsStr(a) === "string" ? JSON.stringify(toJsStr(a)) : raw(a))).join(""));
   });
+  (env as any).set("write-string", (...args: any[]) => { buf.push(raw(args[0])); });
+  (env as any).set("write-char", (...args: any[]) => { buf.push(raw(args[0])); });
   try {
     const results = await Promise.race<any>([
-      (lips as any).exec(preprocessed, env),
+      (lips as any).exec(preprocessed, { env }),
       new Promise((_, reject) =>
         setTimeout(() => reject(new Error(`scheme_eval timed out after ${timeoutMs}ms`)), timeoutMs),
       ),
@@ -516,22 +475,25 @@ async function evaluate(env: any, source: string, timeoutMs: number) {
     let msg = e?.message ?? String(e);
     if (/[Uu]nbalanced parenthes/.test(msg)) {
       msg = formatParenDiagnostic(source, msg);
-    } else if (/Bad escaped character in JSON|Unexpected.*JSON|JSON at position/.test(msg)) {
+    } else if (/Invalid string literal|Bad escaped character|Unexpected.*JSON|JSON at position/.test(msg)) {
       msg = formatStringEscapeDiagnostic(source, msg);
+    } else if (msg.includes("Unbound variable `#\\")) {
+      msg += "\n  Unknown character literal. Supported: #\\newline #\\space #\\tab" +
+        " #\\return #\\null #\\delete #\\escape, #\\xNN, and #\\<char>.";
     }
     return { ok: false as const, error: msg };
   } finally {
-    if (prevStdout !== undefined) (env as any).set("stdout", prevStdout);
-    if (prevDisplay !== undefined) (env as any).set("display", prevDisplay);
+    for (const name of OUTPUT_PROCS) {
+      if (prev[name] !== undefined) (env as any).set(name, prev[name]);
+    }
   }
 }
 
 // ── standard-library shims ───────────────────────────────────────
-// LIPS ships a small subset of R7RS and almost no SRFI-1. Models trained on
-// Racket/Chicken/Guile reach for the canonical names (equal?, member, take,
-// iota, etc.) and hit "Unbound variable" — costing a retry round trip per
-// gap. We pre-populate the most common ones so the model's first attempt
-// works regardless of which Scheme dialect it learned from.
+// Fill the gaps the bootstrapped std library leaves: SRFI-1 helpers, Racket
+// spellings, and cross-dialect aliases. std covers R7RS base, but a model
+// trained on Racket/Chicken/Guile still reaches for names std doesn't bind.
+// defineIfMissing so anything std already provides wins.
 function installStdShims(env: any): void {
   const defineIfMissing = (name: string, fn: any) => {
     if ((env as any).get(name, { throwError: false }) === undefined) env.set(name, fn);
@@ -543,7 +505,6 @@ function installStdShims(env: any): void {
   };
   const truthy = (v: any) => v !== false;
 
-  // ── R7RS equality ─────────────────────────────────────────
   // LIPS wraps numbers as LNumber instances, so `===` fails on equal-valued
   // numbers from different sources. Handle the wrapper types before recursing.
   const atomEqual = (a: any, b: any): boolean => {
@@ -551,7 +512,7 @@ function installStdShims(env: any): void {
     if (a instanceof LNumber && b instanceof LNumber) return a.cmp(b) === 0;
     if (typeof a === "number" && b instanceof LNumber) return LNumber(a).cmp(b) === 0;
     if (typeof b === "number" && a instanceof LNumber) return LNumber(b).cmp(a) === 0;
-    if (a instanceof LSymbol && b instanceof LSymbol) return a.name === b.name;
+    if (a instanceof LSymbol && b instanceof LSymbol) return symName(a) === symName(b);
     return false;
   };
   const lipsEqual = (a: any, b: any): boolean => {
@@ -567,41 +528,13 @@ function installStdShims(env: any): void {
     }
     return false;
   };
-  defineIfMissing("equal?", lipsEqual);
-  defineIfMissing("eqv?", atomEqual);
-
-  // ── R7RS list/member ─────────────────────────────────────
-  defineIfMissing("list?", (v: any) => v === nil || v instanceof Pair);
-  const memberLike = (eq: (a: any, b: any) => boolean) => (item: any, lst: any) => {
-    let p = lst;
-    while (p instanceof Pair) {
-      if (eq(p.car, item)) return p;
-      p = p.cdr;
-    }
-    return false;
-  };
-  defineIfMissing("member", memberLike(lipsEqual));
-  defineIfMissing("memq", memberLike((a, b) => a === b));
-  defineIfMissing("memv", memberLike((a, b) => a === b));
-  defineIfMissing("assv", (item: any, lst: any) => {
-    let p = lst;
-    while (p instanceof Pair) {
-      const e = p.car;
-      if (e instanceof Pair && e.car === item) return e;
-      p = p.cdr;
-    }
-    return false;
-  });
 
-  // ── SRFI-1 list helpers ──────────────────────────────────
   defineIfMissing("first",  (lst: any) => pairToArray(lst)[0]);
   defineIfMissing("second", (lst: any) => pairToArray(lst)[1]);
   defineIfMissing("third",  (lst: any) => pairToArray(lst)[2]);
   defineIfMissing("fourth", (lst: any) => pairToArray(lst)[3]);
   defineIfMissing("fifth",  (lst: any) => pairToArray(lst)[4]);
   defineIfMissing("last",   (lst: any) => { const a = pairToArray(lst); return a[a.length - 1]; });
-  defineIfMissing("take",   (lst: any, n: any) => toSchemeList(pairToArray(lst).slice(0, Number(n))));
-  defineIfMissing("drop",   (lst: any, n: any) => toSchemeList(pairToArray(lst).slice(Number(n))));
   defineIfMissing("take-while", (pred: any, lst: any) => {
     const out: any[] = [];
     for (const x of pairToArray(lst)) { if (!truthy(pred(x))) break; out.push(x); }
@@ -619,7 +552,6 @@ function installStdShims(env: any): void {
     return toSchemeList(Array.from({ length: n }, (_, i) => s + i * k));
   });
   defineIfMissing("any",   (pred: any, lst: any) => pairToArray(lst).some((x) => truthy(pred(x))));
-  defineIfMissing("every", (pred: any, lst: any) => pairToArray(lst).every((x) => truthy(pred(x))));
   defineIfMissing("count", (pred: any, lst: any) => pairToArray(lst).filter((x) => truthy(pred(x))).length);
   defineIfMissing("filter-map", (f: any, lst: any) => {
     const out: any[] = [];
@@ -645,44 +577,8 @@ function installStdShims(env: any): void {
     for (const x of pairToArray(lst)) (truthy(pred(x)) ? t : f).push(x);
     return new Pair(toSchemeList(t), toSchemeList(f));
   });
-  defineIfMissing("fold-right", (f: any, init: any, lst: any) => {
-    const a = pairToArray(lst); let acc = init;
-    for (let i = a.length - 1; i >= 0; i--) acc = f(a[i], acc);
-    return acc;
-  });
-  defineIfMissing("zip", (a: any, b: any) => {
-    const xs = pairToArray(a); const ys = pairToArray(b);
-    const n = Math.min(xs.length, ys.length);
-    return toSchemeList(Array.from({ length: n }, (_, i) => toSchemeList([xs[i], ys[i]])));
-  });
-
-  // ── R7RS numeric predicates / ops ────────────────────────
-  defineIfMissing("zero?",     (n: any) => Number(n) === 0);
-  defineIfMissing("positive?", (n: any) => Number(n) > 0);
-  defineIfMissing("negative?", (n: any) => Number(n) < 0);
-  defineIfMissing("odd?",      (n: any) => Math.abs(Number(n)) % 2 === 1);
-  defineIfMissing("even?",     (n: any) => Number(n) % 2 === 0);
-  defineIfMissing("modulo",    (a: any, b: any) => { const m = Number(a) % Number(b); return (m < 0) === (Number(b) < 0) ? m : m + Number(b); });
-  defineIfMissing("quotient",  (a: any, b: any) => Math.trunc(Number(a) / Number(b)));
-  defineIfMissing("remainder", (a: any, b: any) => Number(a) % Number(b));
-  defineIfMissing("expt",      (a: any, b: any) => Math.pow(Number(a), Number(b)));
-  defineIfMissing("ceiling",   (n: any) => Math.ceil(Number(n)));
-
-  // ── R7RS string ops ──────────────────────────────────────
-  defineIfMissing("string=?",  (a: any, b: any) => String(a) === String(b));
-  defineIfMissing("string<?",  (a: any, b: any) => String(a) < String(b));
-  defineIfMissing("string>?",  (a: any, b: any) => String(a) > String(b));
-  defineIfMissing("string-upcase",   (s: any) => String(s).toUpperCase());
-  defineIfMissing("string-downcase", (s: any) => String(s).toLowerCase());
-  defineIfMissing("string->list",    (s: any) => toSchemeList(Array.from(String(s))));
-  defineIfMissing("list->string",    (lst: any) => pairToArray(lst).map(String).join(""));
-  defineIfMissing("string-ref",      (s: any, i: any) => {
-    const str = String(s);
-    const idx = Math.floor(Number(i));
-    return idx >= 0 && idx < str.length ? str[idx] : false;
-  });
+
   defineIfMissing("string-trim-both", (s: any) => String(s).trim());
-  defineIfMissing("identity", (x: any) => x);
   // Pattern can be string or (regexp "pat"). Racket (?i:…) / (?m:…) inline
   // flag groups are translated to JS RegExp flags.
   const compileRegex = (pat: any): RegExp => {
@@ -698,6 +594,7 @@ function installStdShims(env: any): void {
   };
   defineIfMissing("regexp", (pat: any) => compileRegex(pat));
   const regexpMatch = (pat: any, s: any) => {
+    s = toJsStr(s);
     if (typeof s !== "string") return false;
     const m = s.match(compileRegex(pat));
     return m ? toSchemeList(Array.from(m)) : false;
@@ -720,6 +617,7 @@ function installStdShims(env: any): void {
     return false;
   });
   defineIfMissing("regexp-match-positions", (pat: any, s: any) => {
+    s = toJsStr(s);
     if (typeof s !== "string") return false;
     const m = s.match(compileRegex(pat));
     if (!m) return false;
@@ -728,101 +626,25 @@ function installStdShims(env: any): void {
     return new Pair(full, nil);
   });
 
-  // ── Racket spellings ─────────────────────────────────────
-  defineIfMissing("string-split", (s: any, sep: any) => {
-    if (typeof s !== "string") return nil;
-    if (sep === undefined) return toSchemeList(s.split(/\s+/).filter(Boolean));
-    return toSchemeList(s.split(String(sep)));
-  });
-  defineIfMissing("string-join", (lst: any, sep: any) =>
-    pairToArray(lst).map(String).join(sep === undefined ? " " : String(sep)));
   defineIfMissing("displayln", function (this: any, x: any) {
     const display = (env as any).get("display", { throwError: false });
     if (display) { display(x); display("\n"); }
   });
 
-  // ── R7RS error/exit ──────────────────────────────────────
   defineIfMissing("error", (...msgs: any[]) => {
     throw new Error(msgs.map((m) => (typeof m === "string" ? m : String(m))).join(" "));
   });
   defineIfMissing("void", () => undefined);
 
-  // ── R7RS write (LIPS' display is good enough; write quotes strings) ──
   defineIfMissing("write", function (this: any, x: any) {
     const display = (env as any).get("display", { throwError: false });
     if (display) display(typeof x === "string" ? JSON.stringify(x) : x);
   });
 
-  // ── R7RS numbers (gaps) ────────────────────────────────────
-  defineIfMissing("abs",       (n: any) => Math.abs(Number(n)));
-  defineIfMissing("floor",     (n: any) => Math.floor(Number(n)));
-  defineIfMissing("round",     (n: any) => Math.round(Number(n)));
-  defineIfMissing("truncate",  (n: any) => Math.trunc(Number(n)));
-  defineIfMissing("sqrt",      (n: any) => Math.sqrt(Number(n)));
-  defineIfMissing("log",       (n: any, base: any) =>
-    base === undefined ? Math.log(Number(n)) : Math.log(Number(n)) / Math.log(Number(base)));
-  defineIfMissing("exp",       (n: any) => Math.exp(Number(n)));
-  defineIfMissing("sin",       (n: any) => Math.sin(Number(n)));
-  defineIfMissing("cos",       (n: any) => Math.cos(Number(n)));
-  defineIfMissing("tan",       (n: any) => Math.tan(Number(n)));
-  defineIfMissing("asin",      (n: any) => Math.asin(Number(n)));
-  defineIfMissing("acos",      (n: any) => Math.acos(Number(n)));
-  defineIfMissing("atan",      (a: any, b: any) =>
-    b === undefined ? Math.atan(Number(a)) : Math.atan2(Number(a), Number(b)));
-  defineIfMissing("gcd", (...args: any[]) => {
-    const gcd2 = (a: number, b: number): number => b === 0 ? Math.abs(a) : gcd2(b, a % b);
-    return args.length === 0 ? 0 : args.map(Number).reduce(gcd2);
-  });
-  defineIfMissing("lcm", (...args: any[]) => {
-    const gcd2 = (a: number, b: number): number => b === 0 ? Math.abs(a) : gcd2(b, a % b);
-    const lcm2 = (a: number, b: number): number => a && b ? Math.abs(a * b) / gcd2(a, b) : 0;
-    return args.length === 0 ? 1 : args.map(Number).reduce(lcm2);
-  });
-  defineIfMissing("exact",         (n: any) => Math.round(Number(n)));
-  defineIfMissing("inexact",       (n: any) => Number(n));
-  defineIfMissing("exact->inexact", (n: any) => Number(n));
-  defineIfMissing("inexact->exact", (n: any) => Math.round(Number(n)));
-  defineIfMissing("exact-integer?", (n: any) => Number.isInteger(Number(n)));
-  defineIfMissing("exact?",   (n: any) => Number.isInteger(Number(n)));
-  defineIfMissing("inexact?", (n: any) => !Number.isInteger(Number(n)));
-  defineIfMissing("=", (...args: any[]) => {
-    if (args.length < 2) return true;
-    const first = Number(args[0]);
-    for (let i = 1; i < args.length; i++) if (Number(args[i]) !== first) return false;
-    return true;
-  });
-  defineIfMissing("finite?",        (n: any) => Number.isFinite(Number(n)));
-  defineIfMissing("infinite?",      (n: any) => !Number.isFinite(Number(n)) && !Number.isNaN(Number(n)));
-  defineIfMissing("nan?",           (n: any) => Number.isNaN(Number(n)));
   defineIfMissing("add1", (n: any) => Number(n) + 1);
   defineIfMissing("sub1", (n: any) => Number(n) - 1);
   defineIfMissing("sqr",  (n: any) => Number(n) * Number(n));
 
-  // ── R7RS predicates ────────────────────────────────────────
-  defineIfMissing("boolean?",   (x: any) => x === true || x === false);
-  defineIfMissing("boolean=?",  (a: any, b: any) => a === b && (a === true || a === false));
-  defineIfMissing("procedure?", (x: any) => typeof x === "function");
-  defineIfMissing("symbol?",    (x: any) => x instanceof LSymbol);
-  defineIfMissing("symbol=?",   (a: any, b: any) =>
-    a instanceof LSymbol && b instanceof LSymbol && (a as any).name === (b as any).name);
-  defineIfMissing("string->symbol", (s: any) => new LSymbol(String(s)));
-  defineIfMissing("integer?", (x: any) => typeof x === "number" ? Number.isInteger(x)
-    : (x && typeof x.valueOf === "function" && Number.isInteger(Number(x.valueOf()))));
-
-  // ── R7RS strings (gaps) ────────────────────────────────────
-  defineIfMissing("substring", (s: any, start: any, end: any) => {
-    const str = String(s);
-    const a = Math.max(0, Math.floor(Number(start) || 0));
-    const b = end === undefined ? str.length : Math.min(str.length, Math.floor(Number(end)));
-    return str.slice(a, b);
-  });
-  defineIfMissing("string-copy", (s: any) => String(s));
-  defineIfMissing("make-string", (n: any, ch?: any) => {
-    const len = Math.max(0, Math.floor(Number(n) || 0));
-    const c = ch === undefined ? " " : String(ch);
-    return c.length === 1 ? c.repeat(len) : (c + "").repeat(len).slice(0, len);
-  });
-  defineIfMissing("string-foldcase", (s: any) => String(s).toLowerCase());
   defineIfMissing("string-trim",       (s: any) => String(s).trim());
   defineIfMissing("string-trim-left",  (s: any) => String(s).replace(/^\s+/, ""));
   defineIfMissing("string-trim-right", (s: any) => String(s).replace(/\s+$/, ""));
@@ -830,34 +652,15 @@ function installStdShims(env: any): void {
     String(s).startsWith(String(prefix)));
   defineIfMissing("string-suffix?", (suffix: any, s: any) =>
     String(s).endsWith(String(suffix)));
-  defineIfMissing("non-empty-string?", (x: any) =>
-    typeof x === "string" && x.length > 0);
+  defineIfMissing("non-empty-string?", (x: any) => {
+    x = toJsStr(x);
+    return typeof x === "string" && x.length > 0;
+  });
   defineIfMissing("string-index", (s: any, needle: any) => {
     const i = String(s).indexOf(String(needle));
     return i < 0 ? false : i;
   });
-  defineIfMissing("string-ci=?", (a: any, b: any) =>
-    String(a).toLowerCase() === String(b).toLowerCase());
-  defineIfMissing("string-ci<?", (a: any, b: any) =>
-    String(a).toLowerCase() < String(b).toLowerCase());
-  defineIfMissing("string-ci>?", (a: any, b: any) =>
-    String(a).toLowerCase() > String(b).toLowerCase());
-  defineIfMissing("string<=?",   (a: any, b: any) => String(a) <= String(b));
-  defineIfMissing("string>=?",   (a: any, b: any) => String(a) >= String(b));
-
-  // ── R7RS / SRFI-1 list gaps ────────────────────────────────
-  defineIfMissing("list-tail", (lst: any, n: any) => {
-    let k = Math.floor(Number(n) || 0);
-    let cur: any = lst;
-    while (k-- > 0 && cur instanceof Pair) cur = cur.cdr;
-    return cur;
-  });
-  defineIfMissing("list-ref", (lst: any, n: any) => {
-    let k = Math.floor(Number(n) || 0);
-    let cur: any = lst;
-    while (k-- > 0 && cur instanceof Pair) cur = cur.cdr;
-    return cur instanceof Pair ? cur.car : false;
-  });
+
   defineIfMissing("list-index", (pred: any, lst: any) => {
     let i = 0, cur: any = lst;
     while (cur instanceof Pair) {
@@ -897,13 +700,6 @@ function installStdShims(env: any): void {
     for (let i = args.length - 2; i >= 0; i--) tail = new Pair(args[i], tail);
     return tail;
   });
-  defineIfMissing("list*", (...args: any[]) => {
-    if (args.length === 0) return nil;
-    if (args.length === 1) return args[0];
-    let tail: any = args[args.length - 1];
-    for (let i = args.length - 2; i >= 0; i--) tail = new Pair(args[i], tail);
-    return tail;
-  });
   defineIfMissing("append-reverse", (a: any, b: any) => {
     let cur: any = a, out: any = b;
     while (cur instanceof Pair) { out = new Pair(cur.car, out); cur = cur.cdr; }
@@ -946,26 +742,6 @@ function installStdShims(env: any): void {
     }
     return toSchemeList(out);
   });
-  // LIPS' `range` is single-arg only; override (not defineIfMissing) so the
-  // 1/2/3-arg Racket form wins.
-  env.set("range", (a: any, b: any, step: any) => {
-    let start: number, end: number, st: number;
-    if (b === undefined) { start = 0; end = Number(a); st = 1; }
-    else { start = Number(a); end = Number(b); st = step === undefined ? 1 : Number(step); }
-    const out: number[] = [];
-    if (st > 0) for (let i = start; i < end; i += st) out.push(i);
-    else if (st < 0) for (let i = start; i > end; i += st) out.push(i);
-    return toSchemeList(out);
-  });
-  defineIfMissing("flatten", (lst: any) => {
-    const out: any[] = [];
-    const walk = (x: any) => {
-      if (x instanceof Pair) { let c: any = x; while (c instanceof Pair) { walk(c.car); c = c.cdr; } }
-      else if (x !== nil) out.push(x);
-    };
-    walk(lst);
-    return toSchemeList(out);
-  });
   defineIfMissing("index-of", (lst: any, x: any) => {
     let i = 0, cur: any = lst;
     while (cur instanceof Pair) {
@@ -1017,7 +793,6 @@ function installStdShims(env: any): void {
     return toSchemeList(groups.map((g) => toSchemeList(g.items)));
   });
 
-  // ── Regex (Racket) ─────────────────────────────────────────
   const reCompile = (pat: any): RegExp => {
     if (pat instanceof RegExp) return pat;
     let p = String(pat);
@@ -1031,10 +806,12 @@ function installStdShims(env: any): void {
   };
   defineIfMissing("regexp?", (x: any) => x instanceof RegExp);
   defineIfMissing("regexp-replace", (pat: any, s: any, repl: any) => {
+    s = toJsStr(s);
     if (typeof s !== "string") return s;
     return s.replace(reCompile(pat), String(repl));
   });
   defineIfMissing("regexp-replace*", (pat: any, s: any, repl: any) => {
+    s = toJsStr(s);
     if (typeof s !== "string") return s;
     const re = reCompile(pat);
     const global = re.flags.includes("g") ? re : new RegExp(re.source, re.flags + "g");
@@ -1042,10 +819,11 @@ function installStdShims(env: any): void {
   });
   defineIfMissing("regexp-quote", (s: any) =>
     String(s).replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
-  defineIfMissing("regexp-split", (pat: any, s: any) =>
-    typeof s === "string" ? toSchemeList(s.split(reCompile(pat))) : nil);
+  defineIfMissing("regexp-split", (pat: any, s: any) => {
+    s = toJsStr(s);
+    return typeof s === "string" ? toSchemeList(s.split(reCompile(pat))) : nil;
+  });
 
-  // ── Format (Racket) ────────────────────────────────────────
   // format: simple ~a ~s ~v ~n support — covers most logging/inspection
   defineIfMissing("format", (fmt: any, ...rest: any[]) => {
     const f = String(fmt);
@@ -1074,7 +852,6 @@ function installStdShims(env: any): void {
   defineIfMissing("~v", (...xs: any[]) =>
     xs.map((x) => typeof x === "string" ? JSON.stringify(x) : (x === undefined ? "" : x.toString())).join(""));
 
-  // ── Hash tables (Racket) ───────────────────────────────────
   // Backed by JS Map. Stored as `LipsHash` symbol so we can pattern-match.
   class LipsHash {
     map: Map<any, any> = new Map();
@@ -1082,7 +859,7 @@ function installStdShims(env: any): void {
       if (entries) for (const [k, v] of entries) this.map.set(this._key(k), v);
     }
     _key(k: any): any {
-      if (k instanceof LSymbol) return "::sym::" + (k as any).name;
+      if (k instanceof LSymbol) return "::sym::" + symName(k);
       if (typeof k === "object" && k !== null) return JSON.stringify(k);
       return k;
     }
@@ -1139,20 +916,16 @@ function installStdShims(env: any): void {
   defineIfMissing("hash-values", (h: any) => h instanceof LipsHash ? toSchemeList(h.values()) : nil);
   defineIfMissing("hash-count",  (h: any) => h instanceof LipsHash ? h.size() : 0);
 
-  // ── Sort (R7RS-large / SRFI-132 / Racket) ──────────────────
   // V8's Array.prototype.sort is stable (ES2019), so one impl serves all.
   const sortImpl = (lst: any, less: any) => {
     const arr = pairToArray(lst).slice();
     arr.sort((a, b) => (truthy(less(a, b)) ? -1 : truthy(less(b, a)) ? 1 : 0));
     return toSchemeList(arr);
   };
-  defineIfMissing("sort",  sortImpl);
   defineIfMissing("sort!", sortImpl);
   // SRFI-132 / R7RS-large flips the argument order.
   defineIfMissing("list-sort", (less: any, lst: any) => sortImpl(lst, less));
 
-  // ── Racket list aliases & gaps ─────────────────────────────
-  defineIfMissing("empty?", (v: any) => v === nil);
   defineIfMissing("empty",  nil);
   defineIfMissing("cons?",  (v: any) => v instanceof Pair);
   defineIfMissing("andmap", (pred: any, lst: any) => pairToArray(lst).every((x) => truthy(pred(x))));
@@ -1170,11 +943,6 @@ function installStdShims(env: any): void {
     }
     return false;
   });
-  defineIfMissing("make-list", (n: any, v: any) => {
-    const count = Math.max(0, Math.floor(Number(n) || 0));
-    const fill = v === undefined ? nil : v;
-    return toSchemeList(Array(count).fill(fill));
-  });
   defineIfMissing("build-list", (n: any, proc: any) => {
     const count = Math.max(0, Math.floor(Number(n) || 0));
     const out: any[] = [];
@@ -1196,14 +964,6 @@ function installStdShims(env: any): void {
     const k = Math.max(0, Math.floor(Number(n) || 0));
     return new Pair(toSchemeList(a.slice(0, k)), toSchemeList(a.slice(k)));
   });
-  defineIfMissing("shuffle", (lst: any) => {
-    const a = pairToArray(lst).slice();
-    for (let i = a.length - 1; i > 0; i--) {
-      const j = Math.floor(Math.random() * (i + 1));
-      [a[i], a[j]] = [a[j], a[i]];
-    }
-    return toSchemeList(a);
-  });
   defineIfMissing("add-between", (lst: any, sep: any) => {
     const a = pairToArray(lst);
     if (a.length < 2) return toSchemeList(a);
@@ -1325,16 +1085,8 @@ function installStdShims(env: any): void {
     return toSchemeList(arr.filter((x) => !targets.some((t) => lipsEqual(t, x))));
   });
 
-  // ── Racket numbers (gaps) ──────────────────────────────────
   defineIfMissing("pi", Math.PI);
   // Racket overloads: (random) 0≤x<1, (random k) 0≤i<k, (random lo hi).
-  defineIfMissing("random", (a: any, b: any) => {
-    if (a === undefined) return Math.random();
-    if (b === undefined) return Math.floor(Math.random() * Math.max(0, Math.floor(Number(a))));
-    const lo = Math.floor(Number(a));
-    const hi = Math.floor(Number(b));
-    return lo + Math.floor(Math.random() * Math.max(0, hi - lo));
-  });
   defineIfMissing("exact-floor",    (n: any) => Math.floor(Number(n)));
   defineIfMissing("exact-ceiling",  (n: any) => Math.ceil(Number(n)));
   defineIfMissing("exact-round",    (n: any) => Math.round(Number(n)));
@@ -1353,7 +1105,6 @@ function installStdShims(env: any): void {
     return Number(n).toFixed(d);
   });
 
-  // ── Racket strings & chars (gaps) ──────────────────────────
   defineIfMissing("string-titlecase", (s: any) =>
     String(s).replace(/\b([a-z])/g, (_, c) => c.toUpperCase()));
   defineIfMissing("string-pad", (s: any, width: any, ch?: any) => {
@@ -1368,8 +1119,6 @@ function installStdShims(env: any): void {
     const c = ch === undefined ? " " : String(ch).charAt(0) || " ";
     return str.length >= w ? str : str + c.repeat(w - str.length);
   });
-  defineIfMissing("char-upcase",   (c: any) => String(c).toUpperCase());
-  defineIfMissing("char-downcase", (c: any) => String(c).toLowerCase());
   defineIfMissing("string-normalize-spaces", (s: any, sep?: any, repl?: any) => {
     const str = String(s).trim();
     const splitOn = sep === undefined ? /\s+/ : (sep instanceof RegExp ? sep : new RegExp(String(sep)));
@@ -1383,7 +1132,6 @@ function installStdShims(env: any): void {
     return out;
   });
 
-  // ── Racket hash (gaps) ─────────────────────────────────────
   defineIfMissing("hash-update!", (h: any, k: any, upd: any, dflt: any) => {
     if (!(h instanceof LipsHash)) return h;
     const cur = h.has(k) ? h.get(k) : (typeof dflt === "function" ? dflt() : dflt);
@@ -1462,14 +1210,12 @@ function installStdShims(env: any): void {
   defineIfMissing("make-hasheqv",          (alist?: any) => (env as any).get("make-hash")(alist));
   defineIfMissing("make-immutable-hash",   (alist?: any) => (env as any).get("make-hash")(alist));
 
-  // ── Racket boxes (mutable cells) ───────────────────────────
   class LipsBox { constructor(public v: any) {} }
   defineIfMissing("box",      (v: any) => new LipsBox(v));
   defineIfMissing("box?",     (x: any) => x instanceof LipsBox);
   defineIfMissing("unbox",    (b: any) => b instanceof LipsBox ? b.v : b);
   defineIfMissing("set-box!", (b: any, v: any) => { if (b instanceof LipsBox) b.v = v; return undefined; });
 
-  // ── Environment introspection ──────────────────────────────
   const collectEnvNames = (): string[] => {
     const seen = new Set<string>();
     let cur: any = env;
@@ -1481,28 +1227,26 @@ function installStdShims(env: any): void {
     return Array.from(seen).sort();
   };
   defineIfMissing("defined?", (sym: any) => {
-    const name = sym instanceof LSymbol ? (sym as any).name : String(sym);
+    const name = sym instanceof LSymbol ? symName(sym) : String(sym);
     return (env as any).get(name, { throwError: false }) !== undefined;
   });
   const aproposImpl = (pat: any) => {
-    const needle = pat instanceof LSymbol ? (pat as any).name : String(pat ?? "");
+    const needle = pat instanceof LSymbol ? (symName(pat) ?? "") : String(pat ?? "");
     const re = pat instanceof RegExp ? pat : null;
     const match = (n: string) => re ? re.test(n) : n.includes(needle);
     return toSchemeList(collectEnvNames().filter(match).map((n) => new LSymbol(n)));
   };
-  defineIfMissing("apropos",      aproposImpl);
   defineIfMissing("apropos-list", aproposImpl);
 
-  // ── Misc Racket ────────────────────────────────────────────
   defineIfMissing("current-seconds",      () => Math.floor(Date.now() / 1000));
   defineIfMissing("current-milliseconds", () => Date.now());
   defineIfMissing("current-inexact-milliseconds", () => performance.now());
 }
 
 // Canonical names we claim coverage for. R = R7RS small base; S = SRFI-1;
-// K = Racket racket/base/list/string/format. Continuations, ports, bytevectors,
-// and char predicates are intentionally omitted — they'd be misleading
-// "coverage" without real functionality.
+// K = Racket racket/base/list/string/format. Continuations, ports, and
+// bytevectors are intentionally omitted — they'd be misleading "coverage"
+// without real functionality.
 const COVERAGE_CHECKLIST: string[] = [
   // R7RS § 6.1 equivalence
   "eq?", "eqv?", "equal?",
@@ -1584,6 +1328,10 @@ const COVERAGE_CHECKLIST: string[] = [
   // Racket strings & chars (gaps)
   "string-titlecase", "string-pad", "string-pad-right",
   "char-upcase", "char-downcase",
+  "char->integer", "integer->char", "char?",
+  "char=?", "char<?", "char>?", "char<=?", "char>=?", "char-ci=?",
+  "char-alphabetic?", "char-numeric?", "char-whitespace?",
+  "char-upper-case?", "char-lower-case?", "digit-value",
   "string-normalize-spaces", "build-string",
   // Racket hash
   "make-hash", "hash", "hash?", "hash-ref", "hash-set!", "hash-set",
@@ -1619,7 +1367,7 @@ function auditShimCoverage(env: any): { defined: number; missing: string[] } {
 function unwrapSchemeBool(v: any): any {
   if (v === true || v === false) return v;
   if (v instanceof LSymbol) {
-    const n = (v as any).name;
+    const n = symName(v);
     if (n === "#t") return true;
     if (n === "#f") return false;
   }
@@ -1628,32 +1376,82 @@ function unwrapSchemeBool(v: any): any {
   return v;
 }
 
-// Convert a Scheme alist ((kebab-key . val) …) into the JS object shape
-// the underlying tool expects. Renames keys (kebab→snake), coerces numeric
-// values, and normalizes booleans. Returns {} for non-Pair input.
-function readOptions(
-  value: any,
-  keyMap: Record<string, string>,
-  numericKeys?: Set<string>,
-): Record<string, unknown> {
-  const out: Record<string, unknown> = {};
-  if (!(value instanceof Pair)) return out;
-  let node: any = value;
-  while (node instanceof Pair) {
-    const entry = node.car;
-    if (entry instanceof Pair && entry.car instanceof LSymbol) {
-      const k = (entry.car as any).name;
-      const tgt = keyMap[k];
-      if (tgt !== undefined) {
-        let v: any = entry.cdr;
-        if (numericKeys && numericKeys.has(tgt)) v = Number(v);
-        else v = unwrapSchemeBool(v);
-        out[tgt] = v;
+// Single source of truth for the host primitive surface: drives both the tool
+// description and `(help …)`, so what the model reads matches what it can
+// introspect at runtime. Each binding returns the natural Scheme value for its
+// job; bash returns a record because the exit code has nowhere else to live (a
+// plain bash tool call drops it before the model ever sees it).
+type HostSig = { name: string; sig: string; ret: string; doc: string };
+const HOST_SIGS: HostSig[] = [
+  { name: "bash", sig: '(bash "cmd" [timeout-sec])',
+    ret: "((output . str) (exit-code . n) (error . bool))",
+    doc: "run a shell command; full result. Accessors: output-of exit-code-of ok? error?" },
+  { name: "sh", sig: '(sh "cmd" [timeout-sec])', ret: "str",
+    doc: "run a shell command, return stdout only (stderr text on failure)" },
+  { name: "read-file", sig: '(read-file "path" [offset] [limit])', ret: "str | #f",
+    doc: "file contents, or #f on error. offset is 1-indexed; limit caps lines" },
+  { name: "write-file", sig: '(write-file "path" "content")', ret: "#t | err-str",
+    doc: "overwrite a file" },
+  { name: "edit-file", sig: '(edit-file "path" "old" "new" [replace-all])', ret: "#t | err-str",
+    doc: "replace exact text; pass #t to replace every occurrence" },
+  { name: "grep", sig: '(grep "pat" ["dir"] [:opt val …])',
+    ret: "(listof ((file . str) (line . n) (text . str)))",
+    doc: "ripgrep search. options: :include :case-insensitive :context-before :context-after :limit :offset" },
+  { name: "grep-files", sig: '(grep-files "pat" ["dir"] [:opt val …])', ret: "(listof str)",
+    doc: "files containing a match. options: :include :case-insensitive :limit :offset" },
+  { name: "glob", sig: '(glob "pat" ["dir"])', ret: "(listof str)",
+    doc: "paths matching a glob, mtime-sorted" },
+];
+const sigLine = (h: HostSig): string => `${h.sig} → ${h.ret}`;
+const sigForName = (name: string): string => {
+  const h = HOST_SIGS.find((s) => s.name === name);
+  return h ? sigLine(h) : name;
+};
+
+// Append a primitive's signature to any exception it throws, so a malformed
+// call teaches the right shape in one round-trip instead of a bare stack.
+function withSig(name: string, fn: (...a: any[]) => Promise<any>) {
+  return async (...a: any[]) => {
+    try {
+      return await fn(...a);
+    } catch (e: any) {
+      const base = e?.message ?? String(e);
+      if (!String(base).includes("signature:")) {
+        try { e.message = `${base}\n  signature: ${sigForName(name)}`; } catch { /* frozen */ }
       }
+      throw e;
     }
-    node = node.cdr;
+  };
+}
+
+const isKwSym = (x: any): boolean => {
+  const n = symName(x);
+  return typeof n === "string" && n.startsWith(":");
+};
+
+// Split a host primitive's evaluated arg list into leading positionals and a
+// trailing :key value option map. LIPS has no keyword args, so the grep macros
+// quote leading-colon symbols (otherwise they'd be looked up as unbound
+// variables); they arrive here as plain LSymbols named ":foo".
+function splitArgs(
+  args: any[], keyMap: Record<string, string>, numericKeys?: Set<string>,
+): { positionals: any[]; opts: Record<string, unknown> } {
+  const positionals: any[] = [];
+  let i = 0;
+  while (i < args.length && !isKwSym(args[i])) { positionals.push(args[i]); i++; }
+  const opts: Record<string, unknown> = {};
+  while (i < args.length) {
+    if (!isKwSym(args[i])) { i++; continue; }
+    const tgt = keyMap[symName(args[i])!.slice(1)];
+    if (tgt !== undefined) {
+      const raw = args[i + 1];
+      opts[tgt] = numericKeys && numericKeys.has(tgt)
+        ? Number(raw)
+        : unwrapSchemeBool(toJsStr(raw));
+    }
+    i += 2;
   }
-  return out;
+  return { positionals, opts };
 }
 
 function resolveExecutor(ctx: AgentContext, name: string): ToolExecutor {
@@ -1673,54 +1471,44 @@ function installBindings(
   glob: ToolExecutor | null,
 ): void {
   const runBash = async (command: string, timeoutSec?: number) => {
-    const args: Record<string, unknown> = { command };
+    const args: Record<string, unknown> = { command: toJsStr(command) };
     if (typeof timeoutSec === "number") args.timeout = timeoutSec;
     const result = await bash(args);
-    let content = typeof result.content === "string" ? result.content : String(result.content ?? "");
+    let output = typeof result.content === "string" ? result.content : String(result.content ?? "");
     // Undo bash.ts's "(no output)" sentinel so `(eq? out "")` works.
-    if (content === "(no output)") content = "";
-    return {
-      exitCode: result.exitCode ?? (result.isError ? 1 : 0),
-      stdout: content,
-      stderr: result.isError ? content : "",
-      success: !result.isError,
-    };
+    if (output === "(no output)") output = "";
+    // stdout and stderr are merged upstream — the bash tool surfaces only a
+    // combined `content` — so the record exposes one `output`, not a fabricated
+    // split. `exit-code` is the real shell code and the only channel that
+    // carries it: a plain bash tool call drops it before the model.
+    return { exitCode: result.exitCode ?? (result.isError ? 1 : 0), output, error: result.isError };
   };
-  env.set("bash", async (command: string, timeoutSec?: number) => {
+  env.set("bash", withSig("bash", async (command: string, timeoutSec?: number) => {
     try {
       const r = await runBash(command, timeoutSec);
       return alist([
+        ["output",    r.output],
         ["exit-code", r.exitCode],
-        ["stdout",    r.stdout],
-        ["stderr",    r.stderr],
-        ["success",   r.success],
+        ["error",     r.error],
       ]);
     } catch (e: any) {
       logErr("bash", e, { command, typeofCommand: typeof command });
       throw e;
     }
-  });
-  // Shortcut: return stdout as string. Use `bash` when you need exit-code/stderr.
-  env.set("sh", async (command: string, timeoutSec?: number) => {
+  }));
+  // Shortcut: stdout as a string. Use `bash` when you need the exit code, or
+  // `(ok? (bash "…"))` for a success predicate.
+  env.set("sh", withSig("sh", async (command: string, timeoutSec?: number) => {
     try {
-      const r = await runBash(command, timeoutSec);
-      return r.stdout;
+      return (await runBash(command, timeoutSec)).output;
     } catch (e: any) {
       logErr("sh", e, { command });
       return "";
     }
-  });
-  env.set("sh-ok?", async (command: string, timeoutSec?: number) => {
-    try {
-      const r = await runBash(command, timeoutSec);
-      return r.success;
-    } catch {
-      return false;
-    }
-  });
+  }));
 
-  env.set("read-file", async (filePath: string, offset?: any, limit?: any) => {
-    const args: Record<string, unknown> = { path: filePath, bypass_cache: true };
+  env.set("read-file", withSig("read-file", async (filePath: string, offset?: any, limit?: any) => {
+    const args: Record<string, unknown> = { path: toJsStr(filePath), bypass_cache: true };
     if (offset !== undefined && offset !== null) {
       const n = Number(offset);
       if (!isNaN(n)) args.offset = n;
@@ -1731,19 +1519,21 @@ function installBindings(
     }
     const result = await readFile(args);
     return result.isError ? false : result.content;
-  });
+  }));
 
-  env.set("write-file", async (filePath: string, content: string) => {
+  env.set("write-file", withSig("write-file", async (filePath: string, content: string) => {
+    filePath = toJsStr(filePath); content = toJsStr(content);
     // Re-emit tool lifecycle events so the TUI shows diffs.
     const result = await withDisplay(
       bus, "write_file", "write", { path: filePath, content }, filePath,
       () => writeFile({ path: filePath, content }),
     );
     return result.isError ? result.content : true;
-  });
+  }));
 
   if (editFile) {
-    env.set("edit-file", async (filePath: string, oldStr: string, newStr: string, replaceAll?: any) => {
+    env.set("edit-file", withSig("edit-file", async (filePath: string, oldStr: string, newStr: string, replaceAll?: any) => {
+      filePath = toJsStr(filePath); oldStr = toJsStr(oldStr); newStr = toJsStr(newStr);
       const toolArgs: Record<string, unknown> = { path: filePath, old_text: oldStr, new_text: newStr };
       if (unwrapSchemeBool(replaceAll) === true) toolArgs.replace_all = true;
       const result = await withDisplay(
@@ -1751,18 +1541,18 @@ function installBindings(
         () => editFile(toolArgs),
       );
       return result.isError ? result.content : true;
-    });
+    }));
   }
 
   if (grep) {
-    const GREP_KEYMAP = {
+    const GREP_KEYMAP: Record<string, string> = {
       "include":          "include",
       "case-insensitive": "case_insensitive",
       "context-before":   "context_before",
       "context-after":    "context_after",
       "limit":            "head_limit",
       "offset":           "offset",
-    } as const;
+    };
     const GREP_NUMERIC = new Set([
       "context_before", "context_after", "head_limit", "offset",
     ]);
@@ -1779,93 +1569,96 @@ function installBindings(
         .replace(/\\\+/g, "+").replace(/\\\?/g, "?");
     };
 
-    env.set("%grep", async (pattern: string, p?: string, third?: any) => {
-      const args: Record<string, unknown> = { pattern: normalizePattern(String(pattern ?? "")), output_mode: "content" };
-      if (typeof p === "string") args.path = p;
-      if (third instanceof Pair) {
-        Object.assign(args, readOptions(third, GREP_KEYMAP, GREP_NUMERIC));
-      } else if (third !== undefined && third !== null) {
-        // Back-compat: third positional arg as numeric limit.
-        const n = Number(third);
-        if (!isNaN(n)) args.head_limit = n;
-      }
+    // pattern [path] are positional; everything after is :key value options,
+    // split out by splitArgs (the grep macro quotes the colon symbols).
+    env.set("%grep", withSig("grep", async (...rest: any[]) => {
+      const { positionals, opts } = splitArgs(rest, GREP_KEYMAP, GREP_NUMERIC);
+      const pStr = toJsStr(positionals[1]);
+      const args: Record<string, unknown> = {
+        pattern: normalizePattern(String(positionals[0] ?? "")), output_mode: "content", ...opts,
+      };
+      if (typeof pStr === "string") args.path = pStr;
       const result = await grep(args);
       if (result.isError) return nil;
       if (result.content === "No matches found.") return nil;
       const rows: unknown[] = [];
-      for (const line of stripPagination(result.content)) {
-        const parsed = parseGrepLine(line, typeof p === "string" ? p : undefined);
+      for (const line of stripPagination(result.content as string)) {
+        const parsed = parseGrepLine(line, typeof pStr === "string" ? pStr : undefined);
         if (parsed) rows.push(parsed);
       }
       return toSchemeList(rows);
-    });
+    }));
 
-    env.set("%grep-files", async (pattern: string, p?: string, opts?: any) => {
-      const args: Record<string, unknown> = { pattern: normalizePattern(String(pattern ?? "")), output_mode: "files_with_matches" };
-      if (typeof p === "string") args.path = p;
-      if (opts instanceof Pair) Object.assign(args, readOptions(opts, GREP_KEYMAP, GREP_NUMERIC));
+    env.set("%grep-files", withSig("grep-files", async (...rest: any[]) => {
+      const { positionals, opts } = splitArgs(rest, GREP_KEYMAP, GREP_NUMERIC);
+      const pStr = toJsStr(positionals[1]);
+      const args: Record<string, unknown> = {
+        pattern: normalizePattern(String(positionals[0] ?? "")), output_mode: "files_with_matches", ...opts,
+      };
+      if (typeof pStr === "string") args.path = pStr;
       const result = await grep(args);
       if (result.isError || result.content === "No matches found.") return nil;
-      return toSchemeList(stripPagination(result.content));
-    });
+      return toSchemeList(stripPagination(result.content as string));
+    }));
   }
 
   if (glob) {
     // Strip leading "./" so glob paths match grep's — otherwise eq? on the
     // file field fails across the two.
-    env.set("glob", async (pattern: string, p?: string) => {
-      const args: Record<string, unknown> = { pattern };
-      if (typeof p === "string") args.path = p;
+    env.set("glob", withSig("glob", async (pattern: string, p?: string) => {
+      const pStr = toJsStr(p);
+      const args: Record<string, unknown> = { pattern: toJsStr(pattern) };
+      if (typeof pStr === "string") args.path = pStr;
       const result = await glob(args);
       if (result.isError || result.content === "No files matched.") return nil;
-      const paths = stripPagination(result.content).map((l) =>
+      const paths = stripPagination(result.content as string).map((l) =>
         l.startsWith("./") ? l.slice(2) : l,
       );
       return toSchemeList(paths);
-    });
+    }));
   }
 
-  // Shell-result accessors — JS-side so they're never missing.
+  // Accessors on a bash result — JS-side so they're never missing.
+  env.set("output-of",    (r: unknown) => lookup(r, "output"));
   env.set("exit-code-of", (r: unknown) => lookup(r, "exit-code"));
-  env.set("stdout-of",    (r: unknown) => lookup(r, "stdout"));
-  env.set("stderr-of",    (r: unknown) => lookup(r, "stderr"));
-  env.set("success?",     (r: unknown) => lookup(r, "success") === true);
+  env.set("error?",       (r: unknown) => lookup(r, "error") === true);
+  env.set("ok?",          (r: unknown) => lookup(r, "error") === false);
+
+  // Runtime discovery: (help) lists available host primitives; (help 'grep)
+  // shows one. Filtered to what actually got bound this session.
+  const availableNames = new Set<string>(["bash", "sh", "read-file", "write-file"]);
+  if (editFile) availableNames.add("edit-file");
+  if (grep) { availableNames.add("grep"); availableNames.add("grep-files"); }
+  if (glob) availableNames.add("glob");
+  const availableSigs = HOST_SIGS.filter((h) => availableNames.has(h.name));
+  env.set("help", (name?: any) => {
+    if (name === undefined || name === null) {
+      return availableSigs.map(sigLine).join("\n");
+    }
+    const key = String(name instanceof LSymbol ? symName(name) : toJsStr(name)).replace(/^:/, "");
+    const h = availableSigs.find((s) => s.name === key);
+    return h ? `${sigLine(h)}\n    ${h.doc}` : `no host primitive named ${key}; try (help) for the list`;
+  });
 
   // R7RS / string helpers LIPS doesn't ship.
-  env.set("string-length", (s: unknown) => (typeof s === "string" ? s.length : 0));
-  const stringContains = (s: unknown, needle: unknown) =>
-    typeof s === "string" && typeof needle === "string" && s.includes(needle);
+  const stringContains = (s: unknown, needle: unknown) => {
+    s = toJsStr(s); needle = toJsStr(needle);
+    return typeof s === "string" && typeof needle === "string" && s.includes(needle);
+  };
   env.set("string-contains?", stringContains);
   // Racket spells it without the `?`. Bind both so the model isn't punished
   // for guessing dialect.
   env.set("string-contains", stringContains);
-  env.set("string-append", (...parts: unknown[]) =>
-    parts.map((p) => (p === undefined || p === null ? "" : String(p))).join(""));
-  env.set("number->string", (n: unknown) => String(n));
-  env.set("string->number", (s: unknown) => {
-    if (typeof s !== "string") return false;
-    const n = Number(s);
-    return Number.isNaN(n) ? false : n;
-  });
-  env.set("symbol->string", (sym: any) => (sym && sym.name) ? sym.name : String(sym));
-  // LIPS doesn't ship max/min — useful enough that not having them breaks
-  // common idioms like `(max 1 (- n 5))` for line-bound clamping.
-  env.set("max", (...args: any[]) => args.reduce((a, b) => (Number(a) >= Number(b) ? a : b)));
-  env.set("min", (...args: any[]) => args.reduce((a, b) => (Number(a) <= Number(b) ? a : b)));
-  installStdShims(env);
-  // Global string substitution — LIPS' built-in `replace` with a string
-  // pattern only replaces the first match (it calls JS String.replace).
-  // This binding replaces every occurrence, sed-style.
+  // Global string substitution: `replace` with a string pattern replaces only
+  // the first match; this binding replaces every occurrence, sed-style.
   env.set("string-replace", (oldStr: unknown, newStr: unknown, s: unknown) => {
+    s = toJsStr(s);
     if (typeof s !== "string") return s;
     return s.split(String(oldStr ?? "")).join(String(newStr ?? ""));
   });
 
-  // LIPS' tokenizer doesn't recognize R7RS `#t`/`#f` — they parse as
-  // unbound symbols. Bind them so the natural R7RS reflex works.
-  env.set("#t", true);
-  env.set("#f", false);
   env.set("lines", (s: unknown) => {
+    s = toJsStr(s);
     if (typeof s !== "string" || s.length === 0) return nil;
     const parts = s.split("\n");
     if (parts.length > 0 && parts[parts.length - 1] === "") parts.pop();
@@ -1876,98 +1669,63 @@ function installBindings(
 }
 
 // ── tool registration ─────────────────────────────────────────────
+// Generated from HOST_SIGS so the catalog the model reads matches what
+// `(help …)` reports at runtime.
+const HOST_BINDINGS_BLOCK = HOST_SIGS.map(
+  (h) => `  ${h.sig.padEnd(44)} → ${h.ret}\n      ${h.doc}`,
+).join("\n");
+
 const DESCRIPTION = [
   "Evaluate a Scheme expression (R7RS-compatible).",
   "",
-  "A Scheme runtime with host bindings to the shell, filesystem, search,",
-  "and file editing. Each submission is parsed and evaluated against an",
-  "environment that persists across calls within the session — `define`s",
-  "in one submission are available in the next.",
+  "A Scheme runtime with host bindings to the shell, filesystem, and search.",
+  "The environment persists across calls within a session — `define`s in one",
+  "submission are visible in the next.",
   "",
-  "Productive patterns:",
-  "  - Host bindings (`grep`, `glob`, `read-file`, …) return Scheme data,",
-  "    so the output of one can feed into the next without re-parsing.",
-  "    `(map proc (grep \"pat\" \"src/\"))` is the natural shape.",
-  "  - Read-only calls (`read-file`, `grep`, `glob`, `sh` for queries) have",
-  "    no side effects and can be batched in one submission — bind several",
-  "    with `let`/`define` and assemble the answer locally, instead of",
-  "    issuing each as a separate tool round. Side-effecting calls",
-  "    (`write-file`, `edit-file`, mutating `bash`) are clearer one step",
-  "    at a time so you can react to each result.",
-  "  - The env persists across submissions, so binding intermediate",
-  "    results once (e.g. `(define files (glob …))`) avoids recomputing",
-  "    them in later calls.",
-  "  - `(bash …)` calls a real shell — natural for shell-shaped work",
-  "    (tests, builds, git, system commands). Three variants of the shell",
-  "    binding return different shapes:",
-  "      `(sh \"cmd\")`     → just the output as a string. Fits \"run this,",
-  "                          show me the result\" without unwrapping.",
-  "      `(sh-ok? \"cmd\")` → just a boolean. Fits `(if (sh-ok? \"…\") …)`",
-  "                          branches and existence checks.",
-  "      `(bash \"cmd\")`   → full alist when you need stdout *and* exit",
-  "                          code *and* stderr separately (e.g. capture",
-  "                          stderr while letting stdout flow on).",
-  "    For file content work, the host bindings (`grep`, `read-file`,",
-  "    `glob`) avoid shell-quoting entirely and return structured data.",
-  "  - `scheme-define` saves a procedure to disk so it auto-loads next",
-  "    session — useful when you've worked out something reusable.",
+  "You already know the language: assume the full R7RS / SRFI-1 / Racket stdlib",
+  "is present (map filter fold assoc, string-* and list ops, cond/when/unless,",
+  "char and hash-table ops, …). The only novel surface is the host bindings.",
+  "",
+  "Calling convention:",
+  "  - Required arguments are positional: (read-file \"x\"), (grep \"pat\" \"src/\").",
+  "  - grep / grep-files options are :key value pairs:",
+  "      (grep \"TODO\" \"src/\" :include \"*.ts\" :context-after 2)",
+  "  - Each binding returns the natural Scheme value for its job (a string, a",
+  "    list, a boolean); bash returns a record because you usually want the code.",
   "",
   "Host bindings:",
-  "  (bash cmd [timeout-sec])               → alist ((exit-code . N) (stdout . S) (stderr . S) (success . #t/#f))",
-  "    cmd is run via `bash -c`. Pipes/redirects/$VARS/&&/||/here-docs work",
-  "    inside the string; there's no piping between separate bash calls.",
-  "  (sh cmd [timeout-sec])                 → stdout string (stderr text on failure)",
-  "  (sh-ok? cmd [timeout-sec])             → #t if exit code 0, else #f",
-  "  (read-file path)                       → string, or #f on error",
-  "  (read-file path offset)                → from line offset (1-indexed) to end",
-  "  (read-file path offset limit)          → offset + N lines",
-  "  (write-file path content)              → #t on success, error string on failure",
-  "  (edit-file path old new)               → #t on success, error string on failure",
-  "  (edit-file path old new #t)            → replace every occurrence (not just one)",
-  "  (grep pattern [path] [limit|opts])     → list of ((file . S) (line . N) (text . S))",
-  "  (grep-files pattern [path] [opts])     → list of file paths",
-  "    Patterns are ripgrep regex (Rust). Both POSIX BRE escapes (`\\|`,",
-  "    `\\(`, `\\)`, `\\{`, `\\}`, `\\+`, `\\?`) and bare ERE-style metacharacters",
-  "    (`|`, `(`, `)`, `{`, `}`, `+`, `?`) work — the bridge translates BRE to",
-  "    ERE before invoking ripgrep. `.` is any char, `\\b` is a word boundary.",
-  "    opts: ((include . \"*.ts\")           ; filename glob filter",
-  "           (case-insensitive . #t)",
-  "           (context-before . N) (context-after . N)  ; grep only",
-  "           (limit . N) (offset . N))",
-  "    The opts alist is auto-quoted, so `((k . v) …)` and `'((k . v) …)` both work.",
-  "  (glob pattern [base-dir])              → list of file paths (mtime-sorted)",
-  "Accessors on bash result: (stdout-of r) (stderr-of r) (exit-code-of r) (success? r)",
-  "Strings: (string-length s) (string-contains? s n) (string-append . parts)",
-  "         (string-replace old new s) (number->string n) (string->number s)",
-  "         (lines s) (split sep s) (replace pat repl s)  (max …) (min …)",
+  HOST_BINDINGS_BLOCK,
   "",
-  "Standard Scheme: if cond when unless begin and or not  |  let let* define set! lambda",
-  "  map filter fold reduce for-each  |  eq? null? pair? number? string? empty?",
-  "  list car cdr cons length append reverse assoc  |  define-macro",
+  "  Discover at runtime: (help) lists these, (help 'grep) shows one.",
+  "  bash runs via `bash -c` — pipes/redirects/$VARS/&&/here-docs work inside the",
+  "  string; stdout+stderr are merged into `output`, and `exit-code` is the real",
+  "  shell code. grep/grep-files patterns are ripgrep regex (Rust); POSIX BRE",
+  "  escapes (\\|, \\(, \\), \\{, \\}, \\+, \\?) and bare ERE metacharacters both work.",
   "",
-  "Dialect notes:",
-  "  - R7RS truthy semantics: anything that isn't `#f` is true. `(if str …)`,",
-  "    `(if 0 …)`, `(if '() …)` all take the then-branch.",
-  "  - `#t`/`#f` work as expected. `equal?`, `eq?`, `eqv?`, `string=?` all work.",
-  "  - SRFI-1: `member`, `assq`/`assv`/`assoc`, `delete-duplicates`, `first`",
-  "    through `fifth`, `last`, `take`, `drop`, `iota`, `any`, `every`, `count`,",
-  "    `find`, `filter-map`, `append-map`, `concatenate`, `partition`, `remove`,",
-  "    `delete`, `zip`, `take-while`, `drop-while`, `fold-right` are all bound.",
-  "  - R7RS extras: `string-upcase`/`-downcase`, `string-split`/`-join`,",
-  "    `zero?`/`positive?`/`negative?`/`odd?`/`even?`, `modulo`, `quotient`,",
-  "    `remainder`, `expt`, `ceiling`, `error`, `newline`, `displayln`.",
+  "Composition is the point: chain read-only bindings in one submission so",
+  "intermediate results stay in the Scheme heap instead of the conversation.",
+  "  (map (lambda (m) (read-file (cdr (assoc 'file m)) (cdr (assoc 'line m)) 3))",
+  "       (grep \"TODO\" \"src/\"))",
+  "Side-effecting calls (write-file, edit-file, mutating bash) are clearer one",
+  "at a time so you can react to each result.",
   "",
+  "scheme-define saves a procedure to ~/.agent-sh/scheme-define/{name}.scm so it",
+  "auto-loads next session:",
   "  (scheme-define name (args …) \"docstring\" body …)",
-  "    Defines like `define`, and also saves to",
-  "    ~/.agent-sh/scheme-define/{name}.scm so it auto-loads next session.",
+  "",
+  "Dialect notes:",
+  "  - R7RS truthy semantics: only `#f` is false. `(if 0 …)`, `(if '() …)`,",
+  "    `(if \"\" …)` all take the then-branch.",
+  "  - Characters are a real type: `#\\A` `#\\newline` `#\\space` `#\\tab` `#\\xNN`.",
+  "  - String escapes are JSON-style (`\\\\` `\\\"` `\\n` `\\r` `\\t` `\\uXXXX`);",
+  "    for a literal backslash write `\\\\`.",
   "",
   "Default timeout 15s; pass timeout_ms to override (max 60s).",
 ].join("\n");
 
-// Scheme prelude — R7RS forms LIPS doesn't ship. Evaluated after the JS
-// bindings (#t/#f, null?, etc.) are in place. `define-macro` is LIPS' own
-// macro form (defmacro-style); used here because `define-syntax` isn't
-// available either.
+// Scheme prelude (Lisp `define-macro`s), run after std is bootstrapped.
+// cond/when/unless/newline/assq for convenience; the grep/grep-files macros
+// quote :key option symbols so the bridge can read them as an option map.
 const PRELUDE = `
 (define-macro (cond . clauses)
   (if (null? clauses)
@@ -1989,36 +1747,24 @@ const PRELUDE = `
 (define (newline) (display "\n"))
 (define assq assoc)
 
-;; grep / grep-files: auto-quote alist-literal opts so callers can write
-;; either ((k . v) ...) or '((k . v) ...). Without this, the bare form is
-;; read as a function call on (k . v) and errors with an unbound-variable
-;; message that doesn't point at the cause.
-(define (%alist-literal? x)
-  (and (pair? x) (pair? (car x)) (symbol? (car (car x)))))
-
-(define-macro (grep . args)
-  (if (and (>= (length args) 3) (%alist-literal? (car (cdr (cdr args)))))
-      (cons '%grep
-            (cons (car args)
-                  (cons (car (cdr args))
-                        (cons (list 'quote (car (cdr (cdr args))))
-                              (cdr (cdr (cdr args)))))))
-      (cons '%grep args)))
-
-(define-macro (grep-files . args)
-  (if (and (>= (length args) 3) (%alist-literal? (car (cdr (cdr args)))))
-      (cons '%grep-files
-            (cons (car args)
-                  (cons (car (cdr args))
-                        (cons (list 'quote (car (cdr (cdr args))))
-                              (cdr (cdr (cdr args)))))))
-      (cons '%grep-files args)))
+;; grep / grep-files take :key value options. LIPS has no keyword args, so a
+;; bare :include would be evaluated as an unbound variable; the macro quotes
+;; leading-colon symbols and the %grep bridge splits them from the positionals.
+(define (%kw-symbol? s)
+  (and (symbol? s)
+       (let ((str (symbol->string s)))
+         (and (> (string-length str) 0)
+              (string=? (substring str 0 1) ":")))))
+
+(define (%quote-kw args)
+  (map (lambda (a) (if (%kw-symbol? a) (list 'quote a) a)) args))
+
+(define-macro (grep . args)       (cons '%grep       (%quote-kw args)))
+(define-macro (grep-files . args) (cons '%grep-files (%quote-kw args)))
 `;
 
 export default function activate(ctx: AgentContext): void {
   const env = (lips as any).env.inherit("scheme-ext");
-  installFixedDefine(env);
-  installLenientIf(env);
   const defineRegistry: DefineRegistry = new Map();
   const defineLoading = { active: false };
   // Forward decl: assigned after baseInstruction is computed below.
@@ -2038,21 +1784,32 @@ export default function activate(ctx: AgentContext): void {
   try { glob = resolveExecutor(ctx, "glob"); } catch { /* optional */ }
   installBindings(env, ctx.bus, bash, readFile, writeFile, editFile, grep, glob);
 
-  // Fire-and-forget: exec is async but macros register in <1ms, well before
-  // any user call. Load persisted defines, then audit shim coverage.
-  void (lips as any).exec(PRELUDE, env)
-    .then(() => loadPersistedDefines(env, defineRegistry, defineLoading))
-    .then(() => {
-      const audit = auditShimCoverage(env);
-      if (audit.missing.length > 0) {
-        logErr("shim-audit", new Error("missing canonical names"), {
-          defined: audit.defined,
-          total: audit.defined + audit.missing.length,
-          missing: audit.missing,
-        });
-      }
-    })
-    .catch((e: any) => logErr("prelude", e));
+  // Bootstrap LIPS' compiled std library into the global env, then install the
+  // gap-filling shims (skipped where std already defines a name, so native
+  // R7RS wins), the prelude macros, and any persisted scheme-defines. Bootstrap
+  // must precede installStdShims so native bindings take priority.
+  void (async () => {
+    try {
+      const stdXcb = path.join(
+        path.dirname(createRequire(import.meta.url).resolve("@jcubic/lips")),
+        "std.xcb",
+      );
+      await bootstrap(stdXcb);
+    } catch (e) {
+      logErr("bootstrap", e);
+    }
+    installStdShims(env);
+    await (lips as any).exec(PRELUDE, { env });
+    await loadPersistedDefines(env, defineRegistry, defineLoading);
+    const audit = auditShimCoverage(env);
+    if (audit.missing.length > 0) {
+      logErr("shim-audit", new Error("missing canonical names"), {
+        defined: audit.defined,
+        total: audit.defined + audit.missing.length,
+        missing: audit.missing,
+      });
+    }
+  })().catch((e: any) => logErr("init", e));
 
   if (schemeOnly) {
     for (const name of HIDDEN_IN_SCHEME_ONLY) {
@@ -2085,11 +1842,8 @@ export default function activate(ctx: AgentContext): void {
     },
     getDisplayInfo: () => ({ kind: "execute", icon: "λ", sourceLanguage: "scheme" }),
     formatResult: (args, result) => {
-      // Output is usually a long alist or file dump — the LLM still gets full
-      // content via tool_result, but the TUI body shows the SOURCE so Ctrl+O
-      // reveals what ran rather than what came back. scheme-render.ts (if
-      // loaded) honors this; ashi's default renderer currently ignores
-      // body.kind === "lines", which is fine — summary still carries the gist.
+      // TUI body shows the SOURCE, not the result (Ctrl+O reveals what ran);
+      // the LLM still gets full content via tool_result.
       const sourceLines = String(args.source ?? "").split("\n");
       if (!result.isError) {
         return {
@@ -2120,44 +1874,24 @@ export default function activate(ctx: AgentContext): void {
     },
   });
 
-  // schemeOnly: registerInstruction carries the full tool surface since
-  // deferred-lookup mode strips tool descriptions from the system prompt.
-  // coreTools puts scheme_eval's schema in the API tool list already; we
-  // add behavioral framing here — specifically the context-preservation
-  // nudge that would be lost in the long tool description.
+  // Behavioral framing in the system prompt (the API + examples live in the
+  // tool description). Keep it short and non-duplicative: just when to reach
+  // for scheme_eval over a direct tool call.
   const baseInstruction = schemeOnly
     ? [
         "# Scheme runtime",
-        "scheme_eval is your only tool; see its description for the API.",
-        "",
-        "## Context preservation",
-        "Each tool round-trip permanently consumes context. Prefer composing",
-        "multi-step operations into a single scheme_eval call so intermediate",
-        "results stay in the Scheme heap instead of the conversation. Example:",
-        "  (let ((files (glob \"src/**/*.ts\"))",
-        "         (matches (grep \"TODO\" \"src/\")))",
-        "    (filter (lambda (f) (member f (map (lambda (m) (cdr (assoc 'file m))) matches)))",
-        "            files))",
-        "This does glob + grep + filter in one round-trip. Use `define` to",
-        "cache results across calls: `(define files (glob …))` once, reuse later.",
+        "scheme_eval is your only tool; see its description for the API. Each tool",
+        "round-trip consumes context permanently, so compose multi-step work into a",
+        "single call — intermediate results stay in the Scheme heap, not the",
+        "conversation. `define` caches across calls.",
       ].join("\n")
     : [
         "# Scheme runtime",
-        "scheme_eval evaluates Scheme with host bindings to bash, read-file, grep, glob, etc.",
-        "See its description for the full API.",
-        "",
-        "## When to reach for scheme_eval",
-        "The direct tools (grep, read_file, bash, etc.) are the right default for",
-        "single operations. scheme_eval becomes valuable when you'd chain 2+ read-only",
-        "tool calls that don't need inspection between steps — composing them inside",
-        "Scheme keeps intermediate results in the Scheme heap instead of the",
-        "conversation, saving context. Example:",
-        "  (let ((matches (grep \"pattern\" \"src/\")))",
-        "    (map (lambda (m) (list (cdr (assoc 'file m))",
-        "                           (read-file (cdr (assoc 'file m)) (cdr (assoc 'line m)) 3)))",
-        "         (take matches 5)))",
-        "does grep + read-file × 5 in one round-trip. `define` caches across",
-        "calls: `(define files (glob …))` once, reuse in later submissions.",
+        "scheme_eval evaluates Scheme with host bindings (bash, read-file, grep, glob,",
+        "…); see its description for the API. Direct tools are the right default for",
+        "single operations; reach for scheme_eval to chain 2+ read-only calls that",
+        "don't need inspection between steps — composing them keeps intermediate",
+        "results in the Scheme heap instead of the conversation.",
       ].join("\n");
   // Re-register when the scheme-define registry changes so the index stays
   // current within a session.