agent-sh 0.14.11 → 0.15.0

package/dist/shell/shell-context.js

@@ -1,7 +1,15 @@
 import { getSettings } from "../core/settings.js";
 import { spillOutput } from "../utils/shell-output-spill.js";
+// The cwd-drift note applies only under the shell frontend (where the agent shares
+// the user's cwd); other frontends own a fixed cwd.
+const SHELL_EVENTS_NOTE = `When the user runs shell commands, they appear as \`<shell_events>\` inside \`<query_context>\` on your next turn — use them to ground "fix this" / "what just happened" requests.`;
+const CWD_DRIFT_NOTE = `\`<cwd>\` is the working directory your own tool calls run in: relative paths resolve against it, and it follows the user's shell \`cd\`, so it can change from one turn to the next. Always act on the latest \`<cwd>\`, not one from earlier in the conversation.`;
+const PREFERENCES_NOTE = `Treat the user's commands as standing preferences: check them for recurring patterns and apply them proactively, without waiting to be asked.`;
 export default function activate(ctx) {
     const { bus } = ctx;
+    // The agent shares the user's cwd only under the shell frontend (which installs
+    // ctx.shell); other frontends — e.g. ashi — keep their own fixed cwd.
+    const ownsAgentCwd = !!ctx.shell;
     const exchanges = [];
     let nextId = 1;
     let currentCwd = process.cwd();
@@ -50,23 +58,30 @@ export default function activate(ctx) {
     bus.on("shell:agent-exec-start", () => { agentShellActive = true; });
     bus.on("shell:agent-exec-done", () => { agentShellActive = false; });
     bus.on("shell:user-exec-exclude-next", () => { nextUserExcluded = true; });
-    ctx.advise("cwd", () => currentCwd);
+    if (ownsAgentCwd)
+        ctx.advise("cwd", () => currentCwd);
     // Advise the core handler directly: this loads before the agent host
     // attaches `ctx.agent`, so the sugar isn't available yet.
     ctx.advise("query-context:build", (next) => {
         const base = next();
-        const part = (() => {
-            const cwdTag = `<cwd>${currentCwd}</cwd>`;
-            const fresh = exchanges.filter((ex) => ex.id > lastSeq && ex.source === "user");
-            if (fresh.length === 0)
-                return cwdTag;
+        const fresh = exchanges.filter((ex) => ex.id > lastSeq && ex.source === "user");
+        let shellEvents = "";
+        if (fresh.length > 0) {
             lastSeq = exchanges[exchanges.length - 1].id;
             const text = fresh.map(formatExchangeTruncated).filter(Boolean).join("\n");
-            if (!text)
-                return cwdTag;
-            return `${cwdTag}\n<shell_events>\n${text}\n</shell_events>`;
-        })();
-        return base ? `${base}\n\n${part}` : part;
+            if (text)
+                shellEvents = `<shell_events>\n${text}\n</shell_events>`;
+        }
+        const part = ownsAgentCwd
+            ? [`<cwd>${currentCwd}</cwd>`, shellEvents].filter(Boolean).join("\n")
+            : shellEvents;
+        return [base, part].filter(Boolean).join("\n\n");
+    });
+    bus.onPipe("agent:instructions", (acc) => {
+        const text = [SHELL_EVENTS_NOTE, ownsAgentCwd ? CWD_DRIFT_NOTE : "", PREFERENCES_NOTE]
+            .filter(Boolean).join("\n\n");
+        acc.instructions.push({ name: "shell-events", text });
+        return acc;
     });
     ctx.define("shell:context-recent", (n = 25) => {
         const recent = exchanges.slice(-n);

package/dist/shell/tui-renderer.js

@@ -222,7 +222,6 @@ export default function activate(ctx) {
             }
         }
     });
-    // Track token usage for display
     let pendingUsage = null;
     bus.on("agent:usage", (e) => { pendingUsage = e; });
     bus.on("agent:response-done", () => {

package/dist/utils/diff-renderer.js

@@ -176,17 +176,14 @@ function findChangePairs(hunk) {
     const lines = hunk.lines;
     let i = 0;
     while (i < lines.length) {
-        // Find a run of removed lines
         const removedStart = i;
         while (i < lines.length && lines[i].type === "removed")
             i++;
         const removedEnd = i;
-        // Find a run of added lines immediately after
         const addedStart = i;
         while (i < lines.length && lines[i].type === "added")
             i++;
         const addedEnd = i;
-        // Pair them 1:1
         const removedCount = removedEnd - removedStart;
         const addedCount = addedEnd - addedStart;
         const pairCount = Math.min(removedCount, addedCount);
@@ -254,7 +251,7 @@ function renderUnifiedHunk(hunk, layout) {
     const gutter = (n) => `${p.dim}${n} │${p.reset} `;
     const change = (no, sigil, bg, fg, text) => {
         if (!gutterLine) {
-            return `${bg}${padToWidth(`${no} ${fg}${sigil}${preserveBg(text, bg)}`, textWidth)}${p.reset}`;
+            return `${bg}${fg}${padToWidth(`${no} ${sigil} ${preserveBg(text, bg)}`, textWidth)}${p.reset}`;
         }
         if (useTrueColor)
             return gutter(no) + padToWidth(`${bg}${fg}${sigil} ${preserveBg(text, bg)}`, bgWidth) + p.reset;
@@ -267,7 +264,7 @@ function renderUnifiedHunk(hunk, layout) {
             const raw = truncateText(line.text, lineTextW);
             const text = lang ? highlightLine(raw, lang) : raw;
             // The flush gutter dims only the line number; the code stays normal/highlighted.
-            out.push(!gutterLine ? `${p.dim}${no}${p.reset}  ${text}` : `${gutter(no)}  ${p.dim}${text}${p.reset}`);
+            out.push(!gutterLine ? `${p.dim}${no}${p.reset}   ${text}` : `${gutter(no)}  ${p.dim}${text}${p.reset}`);
             continue;
         }
         if (line.type === "removed") {
@@ -418,19 +415,16 @@ function buildSplitRows(hunk) {
             i++;
             continue;
         }
-        // Collect a run of removed lines
         const removed = [];
         while (i < lines.length && lines[i].type === "removed") {
             removed.push(lines[i]);
             i++;
         }
-        // Collect a run of added lines
         const added = [];
         while (i < lines.length && lines[i].type === "added") {
             added.push(lines[i]);
             i++;
         }
-        // Pair them side by side
         const maxLen = Math.max(removed.length, added.length);
         for (let k = 0; k < maxLen; k++) {
             rows.push({
@@ -517,7 +511,6 @@ function trimHunksToFit(hunks, maxLines) {
                 changeCount++;
         }
     }
-    // Separators between hunks
     const separators = Math.max(0, hunks.length - 1);
     // How many context lines can we afford?
     const contextBudget = Math.max(0, maxLines - changeCount - separators);

package/dist/utils/handler-registry.d.ts

@@ -50,13 +50,8 @@ export declare class HandlerRegistry {
      * Returns undefined if no handler is registered.
      */
     call(name: string, ...args: any[]): any;
-    /**
-     * Check if a named handler exists.
-     */
     has(name: string): boolean;
-    /**
-     * Names of all registered handlers. For diagnostic/introspection use.
-     */
+    /** Names of all registered handlers — for diagnostics/introspection. */
     list(): string[];
 }
 export {};

package/dist/utils/handler-registry.js

@@ -79,15 +79,10 @@ export class HandlerRegistry {
         }
         return fn(...args);
     }
-    /**
-     * Check if a named handler exists.
-     */
     has(name) {
         return this.entries.has(name);
     }
-    /**
-     * Names of all registered handlers. For diagnostic/introspection use.
-     */
+    /** Names of all registered handlers — for diagnostics/introspection. */
     list() {
         return [...this.entries.keys()];
     }

package/dist/utils/line-editor.js

@@ -309,11 +309,9 @@ export class LineEditor {
     pushHistory(line) {
         if (!line.trim())
             return;
-        // Deduplicate: remove if already at top
         if (this.history.length > 0 && this.history[0] === line)
             return;
         this.history.unshift(line);
-        // Cap history size
         if (this.history.length > 100)
             this.history.pop();
     }

package/dist/utils/palette.js

@@ -14,10 +14,10 @@ const defaultPalette = {
     warning: "\x1b[33m", // yellow
     error: "\x1b[31m", // red
     muted: "\x1b[90m", // gray
-    successBg: "\x1b[48;2;0;60;0m",
-    errorBg: "\x1b[48;2;50;0;0m",
-    successBgEmph: "\x1b[48;2;0;112;0m",
-    errorBgEmph: "\x1b[48;2;90;0;0m",
+    successBg: "\x1b[48;2;34;92;43m",
+    errorBg: "\x1b[48;2;122;41;54m",
+    successBgEmph: "\x1b[48;2;56;166;96m",
+    errorBgEmph: "\x1b[48;2;179;89;107m",
     bold: "\x1b[1m",
     dim: "\x1b[2m",
     italic: "\x1b[3m",

package/dist/utils/terminal-buffer.d.ts

@@ -47,6 +47,8 @@ export declare class TerminalBuffer {
     readScreen(opts?: {
         includeScrollback?: boolean;
     }): ScreenSnapshot;
+    /** Read the screen and wrap it as a `<terminal_buffer>` context block. */
+    formatScreen(maxLines?: number, baseContext?: string): string;
     /**
      * Get terminal screen as lines, padded/trimmed to exactly `rows` lines.
      * Clean text only (ANSI stripped).  Reads from the active buffer's

package/dist/utils/terminal-buffer.js

@@ -111,6 +111,10 @@ export class TerminalBuffer {
             cursorY: buf.cursorY,
         };
     }
+    /** Read the screen and wrap it as a `<terminal_buffer>` context block. */
+    formatScreen(maxLines, baseContext) {
+        return formatScreenContext(this.readScreen(), maxLines, baseContext);
+    }
     /**
      * Get terminal screen as lines, padded/trimmed to exactly `rows` lines.
      * Clean text only (ANSI stripped).  Reads from the active buffer's

package/examples/extensions/ash-acp-bridge/src/index.ts

@@ -434,10 +434,10 @@ function waitForModelsToSettle(
       timer = setTimeout(done, Math.max(0, Math.min(quietMs, remaining)));
     };
     const done = () => {
-      core.bus.off("agent:modes-changed", arm);
+      core.bus.off("agent:models-changed", arm);
       resolve();
     };
-    core.bus.on("agent:modes-changed", arm);
+    core.bus.on("agent:models-changed", arm);
     arm();
   });
 }
@@ -446,15 +446,14 @@ function getModelsPayload(): Record<string, unknown> | undefined {
   if (!core) return undefined;
   const info = core.bus.emitPipe("config:get-models", { models: [], active: null });
   if (!info.models.length) return undefined;
-  const idFor = (m: { model: string; provider: string }) =>
-    m.provider ? `${m.model}@${m.provider}` : m.model;
+  const idFor = (m: { id: string; provider: string }) => `${m.id}@${m.provider}`;
   const current = info.active ?? info.models[0]!;
   return {
     currentModelId: idFor(current),
     availableModels: info.models.map((m) => ({
       modelId: idFor(m),
-      name: m.provider ? `${m.provider}/${m.model}` : m.model,
-      description: m.provider ? `Provider: ${m.provider}` : "",
+      name: `${m.provider}/${m.id}`,
+      description: `Provider: ${m.provider}`,
     })),
   };
 }
@@ -601,7 +600,12 @@ function dispatch(msg: JsonRpcRequest): void {
       break;
     case "session/set_model":
       if (core && params?.modelId) {
-        core.bus.emit("config:switch-model", { model: params.modelId as string });
+        const raw = params.modelId as string;
+        const at = raw.lastIndexOf("@");
+        core.bus.emit("config:switch-model", {
+          id: at > 0 ? raw.slice(0, at) : raw,
+          provider: at > 0 ? raw.slice(at + 1) : "",
+        });
       }
       sendResult(id!, {
         models: getModelsPayload() ?? {},

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

@@ -27,7 +27,7 @@ async function withDisplay(
 ): Promise<ToolResult> {
   const toolCallId = `scheme-${toolName}-${++callCounter}`;
   bus.emit("agent:tool-started", {
-    title: toolName, toolCallId, kind, rawInput, displayDetail,
+    title: toolName, toolCallId, kind, rawInput, displayDetail, nested: true,
   });
   const result = await run();
   // Stream the result so the TUI's tracked `output` holds it, not just the summary.
@@ -38,6 +38,7 @@ async function withDisplay(
     rawOutput: result.content,
     kind,
     resultDisplay: result.display,
+    nested: true,
   });
   return result;
 }
@@ -1383,23 +1384,23 @@ function unwrapSchemeBool(v: any): any {
 // 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])',
+  { 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",
+  { 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: "read-file", sig: '(read-file "path" [:offset n] [:limit n])', 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: "edit-file", sig: '(edit-file "path" "old" "new" [:replace-all #t])', ret: "#t | err-str",
+    doc: "replace exact text; :replace-all #t replaces 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" },
+    doc: "ripgrep search. options: :path :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: "files containing a match. options: :path :include :case-insensitive :limit :offset" },
+  { name: "glob", sig: '(glob "pat" [:path "dir"])', ret: "(listof str)",
     doc: "paths matching a glob, mtime-sorted" },
 ];
 const sigLine = (h: HostSig): string => `${h.sig} → ${h.ret}`;
@@ -1429,10 +1430,8 @@ const isKwSym = (x: any): boolean => {
   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".
+// Split a primitive's args into leading positionals and a trailing :key value
+// option map. An unknown key throws so a wrong option name teaches the valid set.
 function splitArgs(
   args: any[], keyMap: Record<string, string>, numericKeys?: Set<string>,
 ): { positionals: any[]; opts: Record<string, unknown> } {
@@ -1442,22 +1441,30 @@ function splitArgs(
   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));
+    const key = symName(args[i])!.slice(1);
+    const tgt = keyMap[key];
+    if (tgt === undefined) {
+      const valid = Object.keys(keyMap).map((k) => `:${k}`).join(" ");
+      throw new Error(`unknown option :${key}; valid options: ${valid || "(none)"}`);
     }
+    const raw = args[i + 1];
+    opts[tgt] = numericKeys && numericKeys.has(tgt)
+      ? Number(raw)
+      : unwrapSchemeBool(toJsStr(raw));
     i += 2;
   }
   return { positionals, opts };
 }
 
+// Cache executors on globalThis (survives reload's module-cache bust): in
+// schemeOnly the built-ins get unregistered, but the tool objects outlive it.
+const EXECUTOR_CACHE: Record<string, ToolExecutor> =
+  ((globalThis as any).__ashSchemeExecutors ??= {});
 function resolveExecutor(ctx: AgentContext, name: string): ToolExecutor {
   const tool = ctx.agent.getTools().find((t) => t.name === name);
-  if (!tool) throw new Error(`scheme bridge: tool '${name}' not registered`);
-  return (args) => tool.execute(args);
+  if (tool) return (EXECUTOR_CACHE[name] = (args) => tool.execute(args));
+  if (EXECUTOR_CACHE[name]) return EXECUTOR_CACHE[name];
+  throw new Error(`scheme bridge: tool '${name}' not registered`);
 }
 
 function installBindings(
@@ -1470,6 +1477,35 @@ function installBindings(
   grep: ToolExecutor | null,
   glob: ToolExecutor | null,
 ): void {
+  // Optional args are :key value pairs; a trailing positional is still accepted.
+  const READ_KEYMAP: Record<string, string> = { "offset": "offset", "limit": "limit" };
+  const READ_NUMERIC = new Set(["offset", "limit"]);
+  const BASH_KEYMAP: Record<string, string> = { "timeout": "timeout" };
+  const BASH_NUMERIC = new Set(["timeout"]);
+  const EDIT_KEYMAP: Record<string, string> = { "replace-all": "replace_all" };
+  const GLOB_KEYMAP: Record<string, string> = { "path": "path" };
+  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",
+    "path":             "path",
+  };
+  const GREP_NUMERIC = new Set([
+    "context_before", "context_after", "head_limit", "offset",
+  ]);
+
+  // LIPS has no keyword-argument syntax: bind each option key to a self-quoting
+  // symbol so a bare `:offset` yields the symbol instead of an unbound error.
+  for (const km of [READ_KEYMAP, BASH_KEYMAP, EDIT_KEYMAP, GLOB_KEYMAP, GREP_KEYMAP]) {
+    for (const key of Object.keys(km)) {
+      const kw = `:${key}`;
+      env.set(kw, new LSymbol(kw));
+    }
+  }
+
   const runBash = async (command: string, timeoutSec?: number) => {
     const args: Record<string, unknown> = { command: toJsStr(command) };
     if (typeof timeoutSec === "number") args.timeout = timeoutSec;
@@ -1483,9 +1519,17 @@ function installBindings(
     // 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", withSig("bash", async (command: string, timeoutSec?: number) => {
+  const bashTimeout = (positionals: any[], opts: Record<string, unknown>): number | undefined => {
+    const t = opts.timeout !== undefined ? opts.timeout : positionals[1];
+    if (t === undefined || t === null) return undefined;
+    const n = Number(t);
+    return isNaN(n) ? undefined : n;
+  };
+  env.set("bash", withSig("bash", async (...rest: any[]) => {
+    const { positionals, opts } = splitArgs(rest, BASH_KEYMAP, BASH_NUMERIC);
+    const command = positionals[0];
     try {
-      const r = await runBash(command, timeoutSec);
+      const r = await runBash(command, bashTimeout(positionals, opts));
       return alist([
         ["output",    r.output],
         ["exit-code", r.exitCode],
@@ -1498,17 +1542,22 @@ function installBindings(
   }));
   // 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) => {
+  env.set("sh", withSig("sh", async (...rest: any[]) => {
+    const { positionals, opts } = splitArgs(rest, BASH_KEYMAP, BASH_NUMERIC);
+    const command = positionals[0];
     try {
-      return (await runBash(command, timeoutSec)).output;
+      return (await runBash(command, bashTimeout(positionals, opts))).output;
     } catch (e: any) {
       logErr("sh", e, { command });
       return "";
     }
   }));
 
-  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 };
+  env.set("read-file", withSig("read-file", async (...rest: any[]) => {
+    const { positionals, opts } = splitArgs(rest, READ_KEYMAP, READ_NUMERIC);
+    const args: Record<string, unknown> = { path: toJsStr(positionals[0]), bypass_cache: true };
+    const offset = opts.offset !== undefined ? opts.offset : positionals[1];
+    const limit = opts.limit !== undefined ? opts.limit : positionals[2];
     if (offset !== undefined && offset !== null) {
       const n = Number(offset);
       if (!isNaN(n)) args.offset = n;
@@ -1532,8 +1581,12 @@ function installBindings(
   }));
 
   if (editFile) {
-    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);
+    env.set("edit-file", withSig("edit-file", async (...rest: any[]) => {
+      const { positionals, opts } = splitArgs(rest, EDIT_KEYMAP);
+      const filePath = toJsStr(positionals[0]);
+      const oldStr = toJsStr(positionals[1]);
+      const newStr = toJsStr(positionals[2]);
+      const replaceAll = opts.replace_all !== undefined ? opts.replace_all : positionals[3];
       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(
@@ -1545,18 +1598,6 @@ function installBindings(
   }
 
   if (grep) {
-    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",
-    };
-    const GREP_NUMERIC = new Set([
-      "context_before", "context_after", "head_limit", "offset",
-    ]);
-
     // Ripgrep uses Rust/ERE regex, but models write BRE (the default flavor
     // of plain grep/sed) where \| \( \) \{ \} \+ \? are metacharacters.
     // Translate BRE escapes to their ERE equivalents so the model's intent is
@@ -1569,33 +1610,33 @@ function installBindings(
         .replace(/\\\+/g, "+").replace(/\\\?/g, "?");
     };
 
-    // 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[]) => {
+    // pattern is positional; search root is the 2nd positional or :path.
+    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 posPath = toJsStr(positionals[1]);
+      if (args.path === undefined && typeof posPath === "string") args.path = posPath;
+      const pStr = typeof args.path === "string" ? args.path : undefined;
       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 as string)) {
-        const parsed = parseGrepLine(line, typeof pStr === "string" ? pStr : undefined);
+        const parsed = parseGrepLine(line, pStr);
         if (parsed) rows.push(parsed);
       }
       return toSchemeList(rows);
     }));
 
-    env.set("%grep-files", withSig("grep-files", async (...rest: any[]) => {
+    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 posPath = toJsStr(positionals[1]);
+      if (args.path === undefined && typeof posPath === "string") args.path = posPath;
       const result = await grep(args);
       if (result.isError || result.content === "No matches found.") return nil;
       return toSchemeList(stripPagination(result.content as string));
@@ -1605,9 +1646,10 @@ function installBindings(
   if (glob) {
     // Strip leading "./" so glob paths match grep's — otherwise eq? on the
     // file field fails across the two.
-    env.set("glob", withSig("glob", async (pattern: string, p?: string) => {
-      const pStr = toJsStr(p);
-      const args: Record<string, unknown> = { pattern: toJsStr(pattern) };
+    env.set("glob", withSig("glob", async (...rest: any[]) => {
+      const { positionals, opts } = splitArgs(rest, GLOB_KEYMAP);
+      const args: Record<string, unknown> = { pattern: toJsStr(positionals[0]) };
+      const pStr = opts.path !== undefined ? String(opts.path) : toJsStr(positionals[1]);
       if (typeof pStr === "string") args.path = pStr;
       const result = await glob(args);
       if (result.isError || result.content === "No files matched.") return nil;
@@ -1687,9 +1729,13 @@ const DESCRIPTION = [
   "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:",
+  "  - Required arguments are positional: (read-file \"x\"), (grep \"pat\").",
+  "  - Optional arguments are :key value pairs, and the same key reads the same",
+  "    on every binding — :offset/:limit on read-file and grep, :timeout on bash:",
+  "      (read-file \"x\" :offset 40 :limit 20)",
   "      (grep \"TODO\" \"src/\" :include \"*.ts\" :context-after 2)",
+  "    (A trailing positional is still accepted for each optional, but :key is",
+  "    the canonical form and never depends on argument order.)",
   "  - 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.",
   "",
@@ -1704,7 +1750,7 @@ const DESCRIPTION = [
   "",
   "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))",
+  "  (map (lambda (m) (read-file (cdr (assoc 'file m)) :offset (cdr (assoc 'line m)) :limit 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.",
@@ -1724,8 +1770,7 @@ const DESCRIPTION = [
 ].join("\n");
 
 // 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.
+// cond/when/unless/newline/assq for convenience.
 const PRELUDE = `
 (define-macro (cond . clauses)
   (if (null? clauses)
@@ -1746,21 +1791,6 @@ const PRELUDE = `
 ;; R7RS shims for things models commonly reach for that LIPS doesn't ship.
 (define (newline) (display "\n"))
 (define assq assoc)
-
-;; 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 {

package/examples/extensions/ashi/EXTENDING.md

@@ -2,6 +2,8 @@
 
 Other extensions can customize how chat entries and tool results render — and even swap the whole TUI renderer — without forking ashi. For non-render concerns (commands, settings, tools, providers) use the standard `agent-sh` extension API; see the [agent-sh extension docs](https://github.com/guanyilun/agent-sh/blob/main/docs/extensions.md).
 
+To **drive** the UI from an extension — post a notice, add a status segment, pin a dock widget, or open a select/confirm/input dialog — use the UI-surface protocol (bus events + named handlers, no `ctx.ui` object); see [`docs/ui-surface-protocol.md`](docs/ui-surface-protocol.md) and the worked example `examples/extensions/ashi-ui-demo.ts`.
+
 ## Chat hooks
 
 These return a renderer-agnostic chat-entry view built from the active renderer's

package/examples/extensions/ashi/README.md

@@ -7,6 +7,14 @@
 
 Same backend, tools, slash commands, providers, and skills as `agent-sh`, mounted in a chat-style interface with session history, branching, and LLM-driven compaction.
 
+Rendering is **decoupled** — even *how* ashi draws tool calls and results is a swappable render extension. Same agent, same conversation; load a different render extension and the whole TUI restyles, no code changes:
+
+| pi-style rendering | claude-code-style rendering |
+|---|---|
+| ![ashi rendering tool calls pi-style](https://raw.githubusercontent.com/guanyilun/agent-sh/main/assets/ashi-pi-style.png) | ![ashi rendering tool calls claude-code-style](https://raw.githubusercontent.com/guanyilun/agent-sh/main/assets/ashi-claude-code-style.png) |
+
+The claude-code-style renderer is [ashi-ink](../ashi-ink), a working Ink (React) renderer; see [Extending ashi](#extending-ashi) for the contract.
+
 ## Install
 
 ```bash
@@ -151,7 +159,7 @@ Each tool inherits from `default` and is overridden by its own block. Unknown to
 ## Extending ashi
 
 Other extensions can customize chat and tool-result rendering — and even swap the whole
-TUI renderer (pi-tui, Ink, …) — without forking ashi. See **[EXTENDING.md](EXTENDING.md)**
+TUI renderer (pi-tui, [Ink](../ashi-ink), …) — without forking ashi. See **[EXTENDING.md](EXTENDING.md)**
 for the chat/tool render hooks, the declarative tool render schema, and the renderer
 contract. For non-render concerns (commands, settings, tools, providers), use the
 standard [agent-sh extension API](https://github.com/guanyilun/agent-sh/blob/main/docs/extensions.md).
@@ -167,6 +175,14 @@ export PATH="$HOME/.agent-sh/bin:$PATH"
 
 `agent-sh install` runs `npm install` and `npm run build` in the copied directory and symlinks the built bin into `~/.agent-sh/bin/`.
 
+By default the copy pulls the **published** `agent-sh` from npm. When ashi's source depends on an unreleased core — a kernel change you haven't published yet — add `--dev` so the install links against the checkout you're running instead:
+
+```bash
+agent-sh install ashi --dev --force
+```
+
+`--dev` repoints the copied package's `agent-sh` dependency at the running host's checkout (the one the global `agent-sh` is linked to). The build then sees the local types, and a later `npm run build` at the repo root flows through without reinstalling — the kernel rebuild rule from [Development](#development) applies. Re-run the install to refresh ashi's own dist after frontend changes.
+
 ## Development
 
 `@guanyilun/ashi` depends on the published `agent-sh` package. To iterate against a local checkout, use `npm link`: