botholomew 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "botholomew",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "An autonomous AI agent for knowledge work — works your task queue while you sleep.",
   "type": "module",
   "bin": {

package/src/chat/agent.ts

@@ -62,6 +62,7 @@ const CHAT_TOOL_NAMES = new Set([
   "skill_edit",
   "skill_search",
   "skill_delete",
+  "sleep",
 ]);
 
 export function getChatTools() {
@@ -364,6 +365,7 @@ export async function runChatTurn(input: {
           projectDir,
           config,
           mcpxClient,
+          shouldAbort: session ? () => session.aborted : undefined,
         });
         const durationMs = Date.now() - start;
         const stored = maybeStoreResult(toolUse.name, result.output);
@@ -411,6 +413,7 @@ interface ChatToolCallCtx {
   projectDir: string;
   config: Required<BotholomewConfig>;
   mcpxClient: McpxClient | null;
+  shouldAbort?: () => boolean;
 }
 
 async function executeChatToolCall(
@@ -434,10 +437,20 @@ async function executeChatToolCall(
   }
 
   try {
-    const result = await withDb(baseCtx.dbPath, (conn) => {
-      const ctx: ToolContext = { ...baseCtx, conn };
-      return tool.execute(parsed.data, ctx);
-    });
+    // `sleep` deliberately yields for up to an hour; opening a DuckDB
+    // connection for that whole window would hold the instance-level file
+    // lock and block any worker that also wants the DB. Run it without a
+    // connection — the tool doesn't touch the DB.
+    const runWithoutDb = tool.name === "sleep";
+    const result = runWithoutDb
+      ? await tool.execute(parsed.data, {
+          ...baseCtx,
+          conn: undefined as unknown as ToolContext["conn"],
+        })
+      : await withDb(baseCtx.dbPath, (conn) => {
+          const ctx: ToolContext = { ...baseCtx, conn };
+          return tool.execute(parsed.data, ctx);
+        });
     const isError =
       typeof result === "object" && result !== null && "is_error" in result
         ? (result as { is_error: boolean }).is_error

package/src/commands/context.ts

@@ -196,9 +196,10 @@ function renderTreeAnsi(
 ): string {
   const lines: string[] = [];
   const connector = isRoot ? "" : isLast ? "└── " : "├── ";
-  const label = node.is_directory
+  const base = node.is_directory
     ? ansis.blue(node.name === "." ? "context/" : `${node.name}/`)
     : node.name;
+  const label = node.is_symlink ? `${base} ${ansis.cyan("→")}` : base;
   lines.push(`${prefix}${connector}${label}`);
   if (node.is_directory && node.children) {
     const childPrefix = isRoot ? "" : prefix + (isLast ? "    " : "│   ");

package/src/context/store.ts

@@ -3,6 +3,7 @@ import {
   copyFile as fsCopyFile,
   readFile as fsReadFile,
   rename as fsRename,
+  lstat,
   mkdir,
   readdir,
   rm,
@@ -69,12 +70,22 @@ export interface ContextEntry {
   path: string;
   is_directory: boolean;
   is_textual: boolean;
+  /**
+   * True when the entry's path under `context/` is a symlink (set from
+   * `lstat`). The agent can read and delete the link, but writes that
+   * traverse a symlink fail with PathEscapeError so external content is
+   * never modified.
+   */
+  is_symlink: boolean;
   size: number;
   mime_type: string;
   mtime: Date;
   content_hash: string | null;
 }
 
+/** Hard cap on directory recursion across walks; defends against pathological symlink graphs. */
+const MAX_WALK_DEPTH = 32;
+
 const TEXTUAL_EXTENSIONS = new Set([
   "md",
   "markdown",
@@ -156,12 +167,18 @@ export function normalizeContextPath(path: string): string {
 
 /**
  * Resolve a context-relative path to an absolute filesystem path under
- * `<projectDir>/context/`. Throws PathEscapeError on traversal, symlinks,
- * NUL bytes, or attempts to resolve into a protected area.
+ * `<projectDir>/context/`. Throws PathEscapeError on traversal, NUL bytes,
+ * or attempts to resolve into a protected area.
+ *
+ * `allowSymlinks` is the opt-in for read-side callers (read, list, tree,
+ * info, reindex, delete). Mutating callers (write, edit, mv, cp, mkdir)
+ * leave it `false` so user-placed symlinks under `context/` cannot be
+ * traversed to modify external content.
  */
 async function resolveContext(
   projectDir: string,
   path: string,
+  opts: { allowSymlinks?: boolean } = {},
 ): Promise<string> {
   const normalized = normalizeContextPath(path);
   if (PROTECTED_AREAS.has(normalized)) {
@@ -172,6 +189,7 @@ async function resolveContext(
   }
   return resolveInRoot(projectDir, fromPosix(normalized), {
     area: CONTEXT_DIR,
+    allowSymlinks: opts.allowSymlinks,
   });
 }
 
@@ -195,7 +213,7 @@ export async function fileExists(
   projectDir: string,
   path: string,
 ): Promise<boolean> {
-  const abs = await resolveContext(projectDir, path);
+  const abs = await resolveContext(projectDir, path, { allowSymlinks: true });
   try {
     await stat(abs);
     return true;
@@ -209,20 +227,45 @@ export async function getInfo(
   projectDir: string,
   path: string,
 ): Promise<ContextEntry | null> {
-  const abs = await resolveContext(projectDir, path);
-  let st: Awaited<ReturnType<typeof stat>>;
+  const abs = await resolveContext(projectDir, path, { allowSymlinks: true });
+  let lst: Awaited<ReturnType<typeof lstat>>;
   try {
-    st = await stat(abs);
+    lst = await lstat(abs);
   } catch (err) {
     if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
     throw err;
   }
+  const isSymlink = lst.isSymbolicLink();
+  let st: Awaited<ReturnType<typeof stat>>;
+  if (isSymlink) {
+    try {
+      st = await stat(abs);
+    } catch (err) {
+      // Broken symlink — surface as a zero-byte symlink entry.
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        return {
+          path: normalizeContextPath(path),
+          is_directory: false,
+          is_textual: false,
+          is_symlink: true,
+          size: 0,
+          mime_type: "application/octet-stream",
+          mtime: lst.mtime,
+          content_hash: null,
+        };
+      }
+      throw err;
+    }
+  } else {
+    st = lst;
+  }
   const normalized = normalizeContextPath(path);
   if (st.isDirectory()) {
     return {
       path: normalized,
       is_directory: true,
       is_textual: false,
+      is_symlink: isSymlink,
       size: 0,
       mime_type: "inode/directory",
       mtime: st.mtime,
@@ -234,6 +277,7 @@ export async function getInfo(
     path: normalized,
     is_directory: false,
     is_textual: textual,
+    is_symlink: isSymlink,
     size: st.size,
     mime_type: mime,
     mtime: st.mtime,
@@ -245,7 +289,7 @@ export async function readContextFile(
   projectDir: string,
   path: string,
 ): Promise<string> {
-  const abs = await resolveContext(projectDir, path);
+  const abs = await resolveContext(projectDir, path, { allowSymlinks: true });
   let st: Awaited<ReturnType<typeof stat>>;
   try {
     st = await stat(abs);
@@ -298,31 +342,42 @@ export async function deleteContextPath(
   projectDir: string,
   path: string,
   opts: { recursive?: boolean } = {},
-): Promise<{ removed: number; was_directory: boolean }> {
-  const abs = await resolveContext(projectDir, path);
+): Promise<{ removed: number; was_directory: boolean; was_symlink: boolean }> {
+  const abs = await resolveContext(projectDir, path, { allowSymlinks: true });
   const normalized = normalizeContextPath(path);
   if (normalized === "") {
     throw new PathEscapeError("refusing to delete the context root", path);
   }
-  let st: Awaited<ReturnType<typeof stat>>;
+  let lst: Awaited<ReturnType<typeof lstat>>;
   try {
-    st = await stat(abs);
+    lst = await lstat(abs);
   } catch (err) {
     if ((err as NodeJS.ErrnoException).code === "ENOENT") {
       throw new NotFoundError(normalized);
     }
     throw err;
   }
-  if (st.isDirectory()) {
+  // A symlink (to a file or a directory, broken or not) is removed with a
+  // plain unlink — never follow into the target. This is what enforces
+  // "the symlink can be deleted, but not the original content".
+  if (lst.isSymbolicLink()) {
+    await unlink(abs);
+    return { removed: 1, was_directory: false, was_symlink: true };
+  }
+  if (lst.isDirectory()) {
     if (!opts.recursive) {
       throw new IsDirectoryError(normalized);
     }
     const removedPaths = await collectFiles(abs);
     await rm(abs, { recursive: true, force: false });
-    return { removed: removedPaths.length, was_directory: true };
+    return {
+      removed: removedPaths.length,
+      was_directory: true,
+      was_symlink: false,
+    };
   }
   await unlink(abs);
-  return { removed: 1, was_directory: false };
+  return { removed: 1, was_directory: false, was_symlink: false };
 }
 
 export async function moveContextPath(
@@ -392,7 +447,7 @@ export async function listContextDir(
   path: string,
   opts: { recursive?: boolean } = {},
 ): Promise<ContextEntry[]> {
-  const abs = await resolveContext(projectDir, path);
+  const abs = await resolveContext(projectDir, path, { allowSymlinks: true });
   let st: Awaited<ReturnType<typeof stat>>;
   try {
     st = await stat(abs);
@@ -406,11 +461,15 @@ export async function listContextDir(
     throw new NotDirectoryError(normalizeContextPath(path));
   }
   const out: ContextEntry[] = [];
+  const visited = new Set<string>();
+  visited.add(`${st.dev}:${st.ino}`);
   await walk(
     abs,
     canonicalContextRoot(projectDir),
     opts.recursive ?? false,
     out,
+    visited,
+    0,
   );
   out.sort((a, b) => a.path.localeCompare(b.path));
   return out;
@@ -421,27 +480,58 @@ async function walk(
   contextRoot: string,
   recursive: boolean,
   acc: ContextEntry[],
+  visited: Set<string>,
+  depth: number,
 ): Promise<void> {
+  if (depth >= MAX_WALK_DEPTH) return;
   const names = await readdir(dir);
   for (const name of names) {
     if (name.startsWith(".")) continue;
     const abs = join(dir, name);
     const rel = toPosix(relative(contextRoot, abs));
-    const { lstat } = await import("node:fs/promises");
-    const st = await lstat(abs);
-    if (st.isSymbolicLink()) continue;
+    const lst = await lstat(abs);
+    const isSymlink = lst.isSymbolicLink();
+    let st: Awaited<ReturnType<typeof stat>>;
+    if (isSymlink) {
+      try {
+        st = await stat(abs);
+      } catch (err) {
+        // Broken symlink — surface as a zero-byte symlink leaf so the agent
+        // can see and remove it, but don't try to recurse into it.
+        if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+          acc.push({
+            path: rel,
+            is_directory: false,
+            is_textual: false,
+            is_symlink: true,
+            size: 0,
+            mime_type: "application/octet-stream",
+            mtime: lst.mtime,
+            content_hash: null,
+          });
+          continue;
+        }
+        throw err;
+      }
+    } else {
+      st = lst;
+    }
     if (st.isDirectory()) {
       acc.push({
         path: rel,
         is_directory: true,
         is_textual: false,
+        is_symlink: isSymlink,
         size: 0,
         mime_type: "inode/directory",
         mtime: st.mtime,
         content_hash: null,
       });
       if (recursive) {
-        await walk(abs, contextRoot, recursive, acc);
+        const key = `${st.dev}:${st.ino}`;
+        if (visited.has(key)) continue;
+        visited.add(key);
+        await walk(abs, contextRoot, recursive, acc, visited, depth + 1);
       }
     } else if (st.isFile()) {
       const { mime, textual } = inferMimeType(rel);
@@ -449,6 +539,7 @@ async function walk(
         path: rel,
         is_directory: false,
         is_textual: textual,
+        is_symlink: isSymlink,
         size: st.size,
         mime_type: mime,
         mtime: st.mtime,
@@ -458,10 +549,25 @@ async function walk(
   }
 }
 
+/**
+ * Collect all real file paths under `absDir`, following symlinks (including
+ * symlinked directories) once each. Used for delete-count reporting and
+ * `dirSizeBytes`. Symlinked entries are returned as the *symlink path*
+ * relative to the walk root, not the resolved target — callers like the
+ * delete reporter want the agent-visible path. Cycles are prevented via a
+ * `dev:ino` visited set seeded with `absDir` itself.
+ */
 async function collectFiles(absDir: string): Promise<string[]> {
   const out: string[] = [];
-  const { lstat } = await import("node:fs/promises");
-  async function recurse(d: string): Promise<void> {
+  const visited = new Set<string>();
+  try {
+    const rootSt = await stat(absDir);
+    visited.add(`${rootSt.dev}:${rootSt.ino}`);
+  } catch {
+    return out;
+  }
+  async function recurse(d: string, depth: number): Promise<void> {
+    if (depth >= MAX_WALK_DEPTH) return;
     let names: string[];
     try {
       names = await readdir(d);
@@ -470,13 +576,24 @@ async function collectFiles(absDir: string): Promise<string[]> {
     }
     for (const name of names) {
       const abs = join(d, name);
-      const st = await lstat(abs);
-      if (st.isSymbolicLink()) continue;
-      if (st.isDirectory()) await recurse(abs);
-      else if (st.isFile()) out.push(abs);
+      let st: Awaited<ReturnType<typeof stat>>;
+      try {
+        st = await stat(abs);
+      } catch {
+        // Broken symlink or permission issue — skip silently.
+        continue;
+      }
+      if (st.isDirectory()) {
+        const key = `${st.dev}:${st.ino}`;
+        if (visited.has(key)) continue;
+        visited.add(key);
+        await recurse(abs, depth + 1);
+      } else if (st.isFile()) {
+        out.push(abs);
+      }
     }
   }
-  await recurse(absDir);
+  await recurse(absDir, 0);
   return out;
 }
 
@@ -484,6 +601,7 @@ export interface TreeNode {
   name: string;
   path: string;
   is_directory: boolean;
+  is_symlink?: boolean;
   size?: number;
   children?: TreeNode[];
 }
@@ -493,7 +611,14 @@ export async function buildTree(
   path: string,
   maxDepth = 16,
 ): Promise<TreeNode> {
-  const abs = await resolveContext(projectDir, path);
+  const abs = await resolveContext(projectDir, path, { allowSymlinks: true });
+  const lst = await lstat(abs).catch((err) => {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new NotFoundError(normalizeContextPath(path));
+    }
+    throw err;
+  });
+  const isSymlink = lst.isSymbolicLink();
   let st: Awaited<ReturnType<typeof stat>>;
   try {
     st = await stat(abs);
@@ -511,10 +636,13 @@ export async function buildTree(
       name,
       path: rel,
       is_directory: false,
+      ...(isSymlink ? { is_symlink: true } : {}),
       size: st.size,
     };
   }
-  return treeRecurse(abs, rel, name, root, maxDepth);
+  const visited = new Set<string>();
+  visited.add(`${st.dev}:${st.ino}`);
+  return treeRecurse(abs, rel, name, root, maxDepth, visited, isSymlink);
 }
 
 async function treeRecurse(
@@ -523,11 +651,14 @@ async function treeRecurse(
   name: string,
   contextRoot: string,
   depthLeft: number,
+  visited: Set<string>,
+  isSymlink: boolean,
 ): Promise<TreeNode> {
   const node: TreeNode = {
     name,
     path: rel,
     is_directory: true,
+    ...(isSymlink ? { is_symlink: true } : {}),
     children: [],
   };
   if (depthLeft <= 0) return node;
@@ -538,24 +669,66 @@ async function treeRecurse(
     return node;
   }
   names.sort((a, b) => a.localeCompare(b));
-  const { lstat } = await import("node:fs/promises");
   const children = node.children ?? [];
   for (const name of names) {
     if (name.startsWith(".")) continue;
     const childAbs = join(abs, name);
-    const st = await lstat(childAbs);
-    if (st.isSymbolicLink()) continue;
+    const lst = await lstat(childAbs);
+    const childIsSymlink = lst.isSymbolicLink();
+    let childSt: Awaited<ReturnType<typeof stat>>;
+    if (childIsSymlink) {
+      try {
+        childSt = await stat(childAbs);
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+          // Broken symlink — render as zero-byte leaf so it shows in the tree.
+          children.push({
+            name,
+            path: toPosix(relative(contextRoot, childAbs)),
+            is_directory: false,
+            is_symlink: true,
+            size: 0,
+          });
+          continue;
+        }
+        throw err;
+      }
+    } else {
+      childSt = lst;
+    }
     const childRel = toPosix(relative(contextRoot, childAbs));
-    if (st.isDirectory()) {
+    if (childSt.isDirectory()) {
+      const key = `${childSt.dev}:${childSt.ino}`;
+      if (visited.has(key)) {
+        // Cycle — render as a stub directory with no children.
+        children.push({
+          name,
+          path: childRel,
+          is_directory: true,
+          ...(childIsSymlink ? { is_symlink: true } : {}),
+          children: [],
+        });
+        continue;
+      }
+      visited.add(key);
       children.push(
-        await treeRecurse(childAbs, childRel, name, contextRoot, depthLeft - 1),
+        await treeRecurse(
+          childAbs,
+          childRel,
+          name,
+          contextRoot,
+          depthLeft - 1,
+          visited,
+          childIsSymlink,
+        ),
       );
-    } else if (st.isFile()) {
+    } else if (childSt.isFile()) {
       children.push({
         name,
         path: childRel,
         is_directory: false,
-        size: st.size,
+        ...(childIsSymlink ? { is_symlink: true } : {}),
+        size: childSt.size,
       });
     }
   }
@@ -567,7 +740,7 @@ export async function dirSizeBytes(
   projectDir: string,
   path: string,
 ): Promise<{ files: number; bytes: number }> {
-  const abs = await resolveContext(projectDir, path);
+  const abs = await resolveContext(projectDir, path, { allowSymlinks: true });
   let st: Awaited<ReturnType<typeof stat>>;
   try {
     st = await stat(abs);

package/src/fs/sandbox.ts

@@ -27,6 +27,15 @@ export interface SandboxOptions {
    * operations like list/tree). Default true.
    */
   allowRoot?: boolean;
+  /**
+   * Permit user-placed symlinks anywhere along the resolved path. The
+   * containment check on the user-supplied path is unchanged — only the
+   * lstat-walk that rejects symlink components is skipped. Read-side
+   * callers (read, list, tree, reindex) opt in; mutating callers do not,
+   * so the agent can never write through a user symlink to external
+   * content.
+   */
+  allowSymlinks?: boolean;
 }
 
 let cachedCanonicalRoot: string | null = null;
@@ -65,8 +74,9 @@ export function getCanonicalRoot(rawRoot: string): string {
  *  3. After path.resolve, the result must be inside the (canonical) root or
  *     `<root>/<area>`.
  *  4. `..` components after normalization are rejected as defense in depth.
- *  5. Every existing path component is `lstat`'d; any symlink is rejected.
- *     Hardlinks are out of scope by design.
+ *  5. Every existing path component is `lstat`'d; any symlink is rejected
+ *     unless `allowSymlinks` is set (read-only callers opt in so users can
+ *     symlink content into `<root>/context/`). Hardlinks are out of scope.
  *
  * Returns the absolute, canonical path safe to pass to fs APIs.
  */
@@ -86,7 +96,9 @@ export async function resolveInRoot(
   const resolved = resolve(boundary, normalized);
   ensureContainment(resolved, boundary, opts.allowRoot ?? true, userPath);
 
-  await assertNoSymlinkComponents(resolved, canonicalRoot);
+  if (!opts.allowSymlinks) {
+    await assertNoSymlinkComponents(resolved, canonicalRoot);
+  }
   return resolved;
 }
 
@@ -109,7 +121,9 @@ export function resolveInRootSync(
   const resolved = resolve(boundary, normalized);
   ensureContainment(resolved, boundary, opts.allowRoot ?? true, userPath);
 
-  assertNoSymlinkComponentsSync(resolved, canonicalRoot);
+  if (!opts.allowSymlinks) {
+    assertNoSymlinkComponentsSync(resolved, canonicalRoot);
+  }
   return resolved;
 }
 

package/src/tools/dir/create.ts

@@ -18,7 +18,7 @@ const outputSchema = z.object({
 export const contextCreateDirTool = {
   name: "context_create_dir",
   description:
-    "[[ bash equivalent command: mkdir -p ]] Create a directory (recursively) under context/.",
+    "[[ bash equivalent command: mkdir -p ]] Create a directory (recursively) under context/. Paths that traverse a user symlink fail with PathEscapeError.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/dir/tree.ts

@@ -21,7 +21,8 @@ export interface BuildContextTreeResult {
 function renderTree(node: TreeNode, prefix = "", isLast = true): string[] {
   const lines: string[] = [];
   const connector = prefix === "" ? "" : isLast ? "└── " : "├── ";
-  const label = node.is_directory ? `${node.name}/` : node.name;
+  const base = node.is_directory ? `${node.name}/` : node.name;
+  const label = node.is_symlink ? `${base} -> (symlink)` : base;
   lines.push(`${prefix}${connector}${label}`);
   if (node.is_directory && node.children) {
     const childPrefix =
@@ -72,7 +73,7 @@ const outputSchema = z.object({
 export const contextTreeTool = {
   name: "context_tree",
   description:
-    "[[ bash equivalent command: tree ]] Render the file tree under context/ (or a sub-directory).",
+    "[[ bash equivalent command: tree ]] Render the file tree under context/ (or a sub-directory). Symlinks are followed for listing and indexing; entries that are symlinks are tagged ' -> (symlink)' in the output.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/file/copy.ts

@@ -26,7 +26,7 @@ const outputSchema = z.object({
 export const contextCopyTool = {
   name: "context_copy",
   description:
-    "[[ bash equivalent command: cp ]] Copy a file under context/ to a new path.",
+    "[[ bash equivalent command: cp ]] Copy a file under context/ to a new path. Source/destination paths that traverse a user symlink fail with PathEscapeError.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/file/delete.ts

@@ -21,6 +21,7 @@ const inputSchema = z.object({
 const outputSchema = z.object({
   deleted: z.number(),
   was_directory: z.boolean(),
+  was_symlink: z.boolean(),
   is_error: z.boolean(),
   error_type: z.string().optional(),
   message: z.string().optional(),
@@ -30,7 +31,7 @@ const outputSchema = z.object({
 export const contextDeleteTool = {
   name: "context_delete",
   description:
-    "[[ bash equivalent command: rm -r ]] Delete a file or (with recursive=true) a directory under context/.",
+    "[[ bash equivalent command: rm -r ]] Delete a file or (with recursive=true) a directory under context/. Symlinks are unlinked without touching their target — `recursive` is not required for a symlinked directory.",
   group: "context",
   inputSchema,
   outputSchema,
@@ -42,16 +43,23 @@ export const contextDeleteTool = {
       return {
         deleted: result.removed,
         was_directory: result.was_directory,
+        was_symlink: result.was_symlink,
         is_error: false,
       };
     } catch (err) {
       if (err instanceof NotFoundError) {
         if (input.force) {
-          return { deleted: 0, was_directory: false, is_error: false };
+          return {
+            deleted: 0,
+            was_directory: false,
+            was_symlink: false,
+            is_error: false,
+          };
         }
         return {
           deleted: 0,
           was_directory: false,
+          was_symlink: false,
           is_error: true,
           error_type: "not_found",
           message: `No file at context/${err.path}`,
@@ -61,6 +69,7 @@ export const contextDeleteTool = {
         return {
           deleted: 0,
           was_directory: true,
+          was_symlink: false,
           is_error: true,
           error_type: "is_directory",
           message: `context/${err.path} is a directory`,

package/src/tools/file/edit.ts

@@ -33,7 +33,7 @@ const outputSchema = z.object({
 export const contextEditTool = {
   name: "context_edit",
   description:
-    "[[ bash equivalent command: patch ]] Apply line-range patches to a file under context/. Each patch specifies start_line/end_line/content.",
+    "[[ bash equivalent command: patch ]] Apply line-range patches to a file under context/. Each patch specifies start_line/end_line/content. Edits that traverse a user symlink fail with PathEscapeError — delete the symlink first or copy the content to a real path.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/file/info.ts

@@ -10,6 +10,7 @@ const fileSchema = z.object({
   path: z.string(),
   is_directory: z.boolean(),
   is_textual: z.boolean(),
+  is_symlink: z.boolean(),
   mime_type: z.string(),
   size: z.number(),
   lines: z.number(),
@@ -28,7 +29,7 @@ const outputSchema = z.object({
 export const contextInfoTool = {
   name: "context_info",
   description:
-    "[[ bash equivalent command: stat ]] Show metadata for a path under context/: size, MIME type, line count, mtime, content hash.",
+    "[[ bash equivalent command: stat ]] Show metadata for a path under context/: size, MIME type, line count, mtime, content hash. `is_symlink` is true when the path is a user-placed symlink.",
   group: "context",
   inputSchema,
   outputSchema,
@@ -52,6 +53,7 @@ export const contextInfoTool = {
         path: info.path,
         is_directory: info.is_directory,
         is_textual: info.is_textual,
+        is_symlink: info.is_symlink,
         mime_type: info.mime_type,
         size: info.size,
         lines,

package/src/tools/file/move.ts

@@ -25,7 +25,7 @@ const outputSchema = z.object({
 export const contextMoveTool = {
   name: "context_move",
   description:
-    "[[ bash equivalent command: mv ]] Move or rename a file/directory under context/.",
+    "[[ bash equivalent command: mv ]] Move or rename a file/directory under context/. Source/destination paths that traverse a user symlink fail with PathEscapeError.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/file/write.ts

@@ -28,7 +28,7 @@ const outputSchema = z.object({
 export const contextWriteTool = {
   name: "context_write",
   description:
-    "[[ bash equivalent command: tee ]] Write text content to a file under context/. Fails if the path already exists unless on_conflict='overwrite'.",
+    "[[ bash equivalent command: tee ]] Write text content to a file under context/. Fails if the path already exists unless on_conflict='overwrite'. Writes that traverse a user symlink fail with PathEscapeError — delete the symlink first or write to a real path.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/registry.ts

@@ -50,6 +50,8 @@ import { listThreadsTool } from "./thread/list.ts";
 import { searchThreadsTool } from "./thread/search.ts";
 import { viewThreadTool } from "./thread/view.ts";
 import { registerTool } from "./tool.ts";
+// Util tools
+import { sleepTool } from "./util/sleep.ts";
 // Worker tools
 import { spawnWorkerTool } from "./worker/spawn.ts";
 
@@ -111,6 +113,9 @@ export function registerAllTools(): void {
   registerTool(mcpInfoTool);
   registerTool(mcpExecTool);
 
+  // Util
+  registerTool(sleepTool);
+
   // Worker
   registerTool(spawnWorkerTool);
 }

package/src/tools/tool.ts

@@ -17,6 +17,11 @@ export interface ToolContext {
   projectDir: string;
   config: Required<BotholomewConfig>;
   mcpxClient: McpxClient | null;
+  /**
+   * Chat-mode only. Lets long-running tools (e.g. `sleep`) poll for
+   * Esc-to-abort by reading `session.aborted`. Workers leave this `undefined`.
+   */
+  shouldAbort?: () => boolean;
 }
 
 type ToolOutputBase = { is_error: z.ZodBoolean };

package/src/tools/util/sleep.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import type { ToolDefinition } from "../tool.ts";
+
+const MIN_SECONDS = 1;
+const MAX_SECONDS = 3600;
+const POLL_INTERVAL_MS = 250;
+
+const inputSchema = z.object({
+  seconds: z
+    .number()
+    .int()
+    .min(MIN_SECONDS)
+    .max(MAX_SECONDS)
+    .describe(
+      `How long to sleep, in seconds (${MIN_SECONDS}–${MAX_SECONDS}). For longer pauses, create a schedule instead.`,
+    ),
+  reason: z
+    .string()
+    .min(1)
+    .describe(
+      "Why you're sleeping — shown to the user under the progress bar. Be specific (e.g. 'waiting for worker to finish task abc').",
+    ),
+});
+
+const outputSchema = z.object({
+  message: z.string(),
+  slept_seconds: z.number(),
+  aborted: z.boolean(),
+  is_error: z.boolean(),
+});
+
+export const sleepTool = {
+  name: "sleep",
+  description:
+    "[[ bash equivalent command: sleep ]] Pause the chat agent for a fixed number of seconds. Useful after enqueuing tasks for workers, before checking results. The user sees a progress bar while you wait; pressing Esc cancels the wait. Returns when the time elapses or the user steers.",
+  group: "util",
+  inputSchema,
+  outputSchema,
+  execute: async (input, ctx): Promise<z.infer<typeof outputSchema>> => {
+    const startedAt = Date.now();
+    const totalMs = input.seconds * 1000;
+    const shouldAbort = ctx.shouldAbort;
+
+    let aborted: boolean = false;
+    await new Promise<void>((resolve) => {
+      let timeout: ReturnType<typeof setTimeout> | null = null;
+      let interval: ReturnType<typeof setInterval> | null = null;
+
+      const finish = () => {
+        if (timeout) clearTimeout(timeout);
+        if (interval) clearInterval(interval);
+        resolve();
+      };
+
+      timeout = setTimeout(finish, totalMs);
+
+      if (shouldAbort) {
+        interval = setInterval(() => {
+          if (shouldAbort()) {
+            aborted = true;
+            finish();
+          }
+        }, POLL_INTERVAL_MS);
+      }
+    });
+
+    const sleptSeconds = (Date.now() - startedAt) / 1000;
+    return {
+      message: aborted
+        ? `Sleep interrupted after ${sleptSeconds.toFixed(1)}s of ${input.seconds}s — user steered.`
+        : `Slept ${sleptSeconds.toFixed(1)}s. ${input.reason}`,
+      slept_seconds: sleptSeconds,
+      aborted,
+      is_error: false,
+    };
+  },
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tui/components/SleepProgress.tsx

@@ -0,0 +1,70 @@
+import { Box, Text } from "ink";
+import { useEffect, useState } from "react";
+import { theme } from "../theme.ts";
+
+interface SleepProgressProps {
+  startedAt: Date;
+  totalSeconds: number;
+  reason?: string;
+}
+
+const BAR_WIDTH = 24;
+const TICK_MS = 200;
+
+export function SleepProgress({
+  startedAt,
+  totalSeconds,
+  reason,
+}: SleepProgressProps) {
+  const [now, setNow] = useState(() => Date.now());
+
+  useEffect(() => {
+    const id = setInterval(() => setNow(Date.now()), TICK_MS);
+    return () => clearInterval(id);
+  }, []);
+
+  const totalMs = totalSeconds * 1000;
+  const elapsedMs = Math.min(totalMs, Math.max(0, now - startedAt.getTime()));
+  const ratio = totalMs > 0 ? elapsedMs / totalMs : 1;
+  const filled = Math.round(ratio * BAR_WIDTH);
+  const bar = "█".repeat(filled) + "░".repeat(BAR_WIDTH - filled);
+  const elapsedSec = (elapsedMs / 1000).toFixed(1);
+
+  return (
+    <Box flexDirection="column">
+      <Box>
+        <Text dimColor>{"    "}</Text>
+        <Text color={theme.accent}>{bar}</Text>
+        <Text dimColor>
+          {" "}
+          {elapsedSec}s / {totalSeconds}s
+        </Text>
+      </Box>
+      {reason && (
+        <Text dimColor wrap="truncate-end">
+          {"    "}
+          {reason}
+        </Text>
+      )}
+    </Box>
+  );
+}
+
+/**
+ * Pull `seconds` and `reason` out of a sleep tool's stringified JSON input.
+ * Returns `null` if the input can't be parsed or doesn't have a numeric duration.
+ */
+export function parseSleepInput(
+  raw: string,
+): { seconds: number; reason?: string } | null {
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed?.seconds !== "number") return null;
+    return {
+      seconds: parsed.seconds,
+      reason: typeof parsed.reason === "string" ? parsed.reason : undefined,
+    };
+  } catch {
+    return null;
+  }
+}

package/src/tui/components/ToolCall.tsx

@@ -1,5 +1,6 @@
 import { Box, Text } from "ink";
 import { theme } from "../theme.ts";
+import { parseSleepInput, SleepProgress } from "./SleepProgress.tsx";
 
 /**
  * For mcp_exec calls, extract server/tool into a top-level display name
@@ -53,6 +54,8 @@ export function ToolCall({ tool }: ToolCallProps) {
   const truncatedInput =
     displayInput.length > 60 ? `${displayInput.slice(0, 60)}…` : displayInput;
   const truncatedOutput = tool.output ? tool.output.slice(0, 120) : "";
+  const sleepArgs =
+    tool.name === "sleep" && tool.running ? parseSleepInput(tool.input) : null;
 
   return (
     <Box flexDirection="column">
@@ -83,6 +86,13 @@ export function ToolCall({ tool }: ToolCallProps) {
         {tool.name === "mcp_exec" && <Text dimColor> (exec)</Text>}
         <Text dimColor> ({truncatedInput})</Text>
       </Box>
+      {sleepArgs && (
+        <SleepProgress
+          startedAt={tool.timestamp}
+          totalSeconds={sleepArgs.seconds}
+          reason={sleepArgs.reason}
+        />
+      )}
       {truncatedOutput && !tool.running && (
         <Text dimColor wrap="truncate-end">
           {"    → "}