obol-ai 0.2.22 → 0.2.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "obol-ai",
-  "version": "0.2.22",
+  "version": "0.2.23",
   "description": "Self-evolving AI assistant that learns, remembers, and acts on its own. Persistent vector memory, self-rewriting personality, proactive heartbeats.",
   "main": "src/index.js",
   "bin": {

package/src/claude/chat.js

@@ -99,6 +99,7 @@ function createClaude(anthropicConfig, { personality, memory, userDir = OBOL_DIR
     context._reloadPersonality = reloadPersonality;
     context._abortSignal = abortController.signal;
     context._forceSignal = forceController.signal;
+    context.claude = { chat, clearHistory, client };
     const runnableTools = buildRunnableTools(tools, memory, context, vlog);
     let activeModel = model;
 

package/src/claude/tool-registry.js

@@ -12,6 +12,7 @@ const schedulerTool = require('./tools/scheduler');
 const ttsTool = require('./tools/tts');
 const bridgeTool = require('./tools/bridge');
 const historyTool = require('./tools/history');
+const agentTool = require('./tools/agent');
 
 const TOOL_MODULES = [
   execTool,
@@ -24,17 +25,22 @@ const TOOL_MODULES = [
   schedulerTool,
   ttsTool,
   historyTool,
+  agentTool,
 ];
 
 const INPUT_SUMMARIES = {
   exec: (i) => i.command,
   write_file: (i) => i.path,
-  read_file: (i) => i.path,
+  read_file: (i) => i.offset ? `${i.path}:${i.offset}` : i.path,
+  edit_file: (i) => i.path,
+  glob: (i) => i.pattern,
+  grep: (i) => `${i.pattern}${i.path ? ` in ${i.path}` : ''}`,
   memory_search: (i) => i.query,
   memory_add: (i) => `[${i.category || 'fact'}]`,
   memory_remove: (i) => i.ids?.join(', '),
   memory_query: (i) => `${i.date || ''}${i.tags ? ' #' + i.tags.join(' #') : ''}${i.category ? ' [' + i.category + ']' : ''}`.trim() || 'all',
   web_search: (i) => i.query,
+  agent: (i) => i.task?.substring(0, 60),
   background_task: (i) => i.task?.substring(0, 60),
   schedule_event: (i) => `${i.title} @ ${i.due_at}${i.cron_expr ? ` [${i.cron_expr}]` : ''}`,
   cancel_event: (i) => i.event_id,

package/src/claude/tools/agent.js

@@ -0,0 +1,40 @@
+const definitions = [{
+  name: 'agent',
+  description: 'Spawn a focused sub-agent to handle a specific task and return the result. Use for research, file analysis, or any multi-step work that would clutter the main conversation. Defaults to haiku — use sonnet for tasks requiring deeper reasoning.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      task: { type: 'string', description: 'Detailed description of what the sub-agent should do' },
+      model: { type: 'string', enum: ['haiku', 'sonnet'], description: 'Model to use (default: haiku)' },
+    },
+    required: ['task'],
+  },
+}];
+
+const handlers = {
+  async agent(input, memory, context) {
+    const { claude } = context;
+    if (!claude) return 'Agent tool not available in this context.';
+
+    const depth = context._agentDepth || 0;
+    if (depth >= 2) return 'Error: max agent nesting depth reached.';
+
+    const model = input.model === 'sonnet' ? 'claude-sonnet-4-6' : 'claude-haiku-4-5-20251001';
+    const subChatId = `agent-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+
+    const { text } = await claude.chat(input.task, {
+      chatId: subChatId,
+      _agentDepth: depth + 1,
+      _model: model,
+      userDir: context.userDir,
+      toolPrefs: context.toolPrefs,
+      verbose: context.verbose,
+      _verboseNotify: context._verboseNotify,
+    });
+
+    claude.clearHistory(subChatId);
+    return text || '(agent completed with no output)';
+  },
+};
+
+module.exports = { definitions, handlers };

package/src/claude/tools/exec.js

@@ -1,6 +1,31 @@
-const { MAX_EXEC_TIMEOUT, BLOCKED_EXEC_PATTERNS, SENSITIVE_READ_PATHS } = require('../constants');
+const { MAX_EXEC_TIMEOUT, BLOCKED_EXEC_PATTERNS } = require('../constants');
 const { execAsync } = require('../../sanitize');
 
+const ALLOWED_PATH_PREFIXES = [
+  '/usr/', '/bin/', '/sbin/', '/lib/', '/lib64/', '/lib32/',
+  '/opt/',
+  '/tmp/',
+  '/dev/null', '/dev/stdout', '/dev/stderr', '/dev/stdin',
+  '/proc/self/',
+];
+
+/** Extract absolute path tokens from a shell command */
+function extractAbsolutePaths(command) {
+  const re = /(?:^|[\s=|&;<>('"])(\/[\w.\-/]*)/g;
+  const paths = new Set();
+  let m;
+  while ((m = re.exec(command)) !== null) {
+    paths.add(m[1]);
+  }
+  return [...paths];
+}
+
+/** Returns true if path is within userDir or a safe system prefix */
+function isAllowedPath(p, userDir) {
+  if (p === userDir || p.startsWith(userDir + '/')) return true;
+  return ALLOWED_PATH_PREFIXES.some(prefix => p.startsWith(prefix));
+}
+
 const definitions = [{
   name: 'exec',
   description: 'Execute a shell command and return the output. Use for file operations, system tasks, running scripts.',
@@ -23,10 +48,9 @@ const handlers = {
       }
     }
     if (userDir) {
-      for (const pattern of SENSITIVE_READ_PATHS) {
-        if (pattern.test(input.command)) {
-          return `Blocked: command accesses a sensitive path. Ask the user for confirmation first.`;
-        }
+      const blockedPaths = extractAbsolutePaths(input.command).filter(p => !isAllowedPath(p, userDir));
+      if (blockedPaths.length > 0) {
+        return `Blocked: command accesses path(s) outside your workspace: ${blockedPaths.join(', ')}`;
       }
     }
     const timeout = Math.min(input.timeout || 30, MAX_EXEC_TIMEOUT) * 1000;

package/src/claude/tools/files.js

@@ -1,4 +1,5 @@
 const fs = require('fs');
+const fsPromises = require('fs/promises');
 const path = require('path');
 const { execFileSync } = require('child_process');
 const { resolveUserPath } = require('../utils');
@@ -6,11 +7,13 @@ const { resolveUserPath } = require('../utils');
 const definitions = [
   {
     name: 'read_file',
-    description: 'Read contents of a file. Supports text files and PDFs (extracts text from PDF automatically).',
+    description: 'Read contents of a file. Supports text files and PDFs. Use offset and limit for large files.',
     input_schema: {
       type: 'object',
       properties: {
         path: { type: 'string', description: 'File path' },
+        offset: { type: 'number', description: 'Line number to start reading from (1-based)' },
+        limit: { type: 'number', description: 'Number of lines to read' },
       },
       required: ['path'],
     },
@@ -27,6 +30,43 @@ const definitions = [
       required: ['path', 'content'],
     },
   },
+  {
+    name: 'edit_file',
+    description: 'Replace an exact string in a file. old_string must appear exactly once. Prefer this over write_file for surgical edits.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'File path' },
+        old_string: { type: 'string', description: 'Text to replace — must be unique in the file' },
+        new_string: { type: 'string', description: 'Replacement text' },
+      },
+      required: ['path', 'old_string', 'new_string'],
+    },
+  },
+  {
+    name: 'glob',
+    description: 'Find files matching a glob pattern within your workspace. E.g. **/*.js, scripts/*.sh, test-*.js',
+    input_schema: {
+      type: 'object',
+      properties: {
+        pattern: { type: 'string', description: 'Glob pattern' },
+      },
+      required: ['pattern'],
+    },
+  },
+  {
+    name: 'grep',
+    description: 'Search file contents for a pattern within your workspace. Returns matching lines with file and line number.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        pattern: { type: 'string', description: 'Search pattern (regex)' },
+        path: { type: 'string', description: 'File or directory to search (default: workspace root)' },
+        glob: { type: 'string', description: 'Limit search to files matching this glob pattern, e.g. *.js' },
+      },
+      required: ['pattern'],
+    },
+  },
   {
     name: 'send_file',
     description: 'Send a file to the user via Telegram (PDF, image, document, etc). Use after generating files the user requested.',
@@ -59,14 +99,22 @@ const handlers = {
     const filePath = userDir ? resolveUserPath(input.path, userDir) : input.path;
     if (filePath.toLowerCase().endsWith('.pdf')) {
       const pdfParse = require('pdf-parse');
-      const pdfBuffer = fs.readFileSync(filePath);
-      const { text } = await pdfParse(pdfBuffer);
-      const truncatedPdf = text.substring(0, 50000);
-      return text.length > 50000 ? truncatedPdf + '\n...(truncated)' : truncatedPdf;
+      const { text } = await pdfParse(fs.readFileSync(filePath));
+      const truncated = text.substring(0, 50000);
+      return text.length > 50000 ? truncated + '\n...(truncated)' : truncated;
+    }
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    if (input.offset || input.limit) {
+      const lines = raw.split('\n');
+      const start = Math.max(0, (input.offset || 1) - 1);
+      const slice = input.limit ? lines.slice(start, start + input.limit) : lines.slice(start);
+      const numbered = slice.map((l, i) => `${start + i + 1}\t${l}`).join('\n');
+      const totalLines = lines.length;
+      const end = start + slice.length;
+      return `Lines ${start + 1}-${end} of ${totalLines}:\n${numbered}`;
     }
-    const fileContent = fs.readFileSync(filePath, 'utf-8');
-    const truncatedFile = fileContent.substring(0, 50000);
-    return fileContent.length > 50000 ? truncatedFile + '\n...(truncated)' : truncatedFile;
+    const truncated = raw.substring(0, 50000);
+    return raw.length > 50000 ? truncated + '\n...(truncated)' : truncated;
   },
 
   async write_file(input, memory, context) {
@@ -80,6 +128,50 @@ const handlers = {
     return `Written: ${filePath}`;
   },
 
+  async edit_file(input, memory, context) {
+    const { userDir } = context;
+    const filePath = userDir ? resolveUserPath(input.path, userDir) : input.path;
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const count = content.split(input.old_string).length - 1;
+    if (count === 0) return `Error: old_string not found in ${input.path}`;
+    if (count > 1) return `Error: old_string matches ${count} times — add more context to make it unique`;
+    fs.writeFileSync(filePath, content.replace(input.old_string, input.new_string));
+    if (path.basename(filePath) === 'traits.json' || filePath.includes('personality/')) {
+      context._reloadPersonality?.();
+    }
+    return `Edited: ${filePath}`;
+  },
+
+  async glob(input, memory, context) {
+    const { userDir } = context;
+    const cwd = userDir || '/tmp';
+    const files = [];
+    for await (const f of fsPromises.glob(input.pattern, { cwd })) {
+      files.push(f);
+    }
+    if (files.length === 0) return 'No files found matching pattern.';
+    return files.sort().join('\n');
+  },
+
+  async grep(input, memory, context) {
+    const { userDir } = context;
+    const searchRoot = input.path
+      ? resolveUserPath(input.path, userDir)
+      : (userDir || '/tmp');
+    const args = ['-r', '-n', '--include', input.glob || '*', input.pattern, searchRoot];
+    try {
+      const output = execFileSync('grep', args, { encoding: 'utf-8', maxBuffer: 1024 * 1024 });
+      const lines = output.trim().split('\n');
+      // Make paths relative to userDir for cleaner output
+      const relative = lines.map(l => l.replace(searchRoot + '/', ''));
+      const truncated = relative.slice(0, 200);
+      return truncated.join('\n') + (lines.length > 200 ? `\n...(${lines.length - 200} more lines)` : '');
+    } catch (e) {
+      if (e.status === 1) return 'No matches found.';
+      throw e;
+    }
+  },
+
   async send_file(input, memory, context) {
     const { userDir } = context;
     const filePath = userDir ? resolveUserPath(input.path, userDir) : input.path;

package/src/clean.js

@@ -1,19 +1,7 @@
-/**
- * Workspace cleaner — audits ~/.obol/ for misplaced files and rogue directories.
- *
- * Known structure:
- *   config.json, .evolution-state.json, .first-run-done, .post-setup-done
- *   personality/, scripts/, tests/, commands/, apps/, logs/
- *
- * Everything else is flagged. Rogue directories and unknown files are removed.
- * Misplaced files (e.g. a .js in personality/) are moved to the correct location.
- */
-
 const fs = require('fs');
 const path = require('path');
 const { OBOL_DIR } = require('./config');
 
-// Allowed top-level entries
 const ALLOWED_DIRS = new Set(['personality', 'scripts', 'tests', 'commands', 'apps', 'logs', 'assets']);
 const ALLOWED_FILES = new Set([
   'config.json',
@@ -21,121 +9,248 @@ const ALLOWED_FILES = new Set([
   '.first-run-done',
   '.post-setup-done',
 ]);
-// Files that can appear at top level with any name
-const ALLOWED_PATTERNS = [
-  /^\./, // Hidden files (dotfiles)
-];
+const ALLOWED_PATTERNS = [/^\./];
 
-// Where file types belong
 const FILE_RULES = {
   '.js': 'scripts',
   '.sh': 'scripts',
-  '.md': 'commands', // .md files outside personality/ are probably commands
+  '.md': 'commands',
 };
 
-async function cleanWorkspace(userDir) {
-  const baseDir = userDir || OBOL_DIR;
-  const issues = [];
-  const errors = [];
+const DIR_FILE_RULES = {
+  personality: ['.md'],
+  scripts: ['.js', '.sh'],
+  tests: ['.js', '.sh'],
+  commands: ['.md'],
+};
 
-  if (!fs.existsSync(baseDir)) {
-    return { issues, errors: ['Directory does not exist'] };
-  }
+function safeReaddir(dir) {
+  try {
+    return fs.readdirSync(dir).filter(f => {
+      try { return fs.statSync(path.join(dir, f)).isFile(); } catch { return false; }
+    });
+  } catch { return []; }
+}
 
-  const entries = fs.readdirSync(baseDir, { withFileTypes: true });
+function safeReaddirAll(dir) {
+  try { return fs.readdirSync(dir); } catch { return []; }
+}
 
-  for (const entry of entries) {
-    const fullPath = path.join(baseDir, entry.name);
+function guessDestination(filename) {
+  const ext = path.extname(filename);
+  if (filename.startsWith('test-') || filename.startsWith('test_')) return 'tests';
+  return FILE_RULES[ext] || null;
+}
+
+/**
+ * @param {string} userDir
+ * @returns {Array<{type: string, name: string, children?: string[], currentDir?: string}>}
+ */
+function scanWorkspace(userDir) {
+  const rogueItems = [];
+  if (!fs.existsSync(userDir)) return rogueItems;
 
+  const entries = fs.readdirSync(userDir, { withFileTypes: true });
+
+  for (const entry of entries) {
     if (entry.isDirectory()) {
       if (!ALLOWED_DIRS.has(entry.name) && !entry.name.startsWith('.')) {
-        const files = safeReaddir(fullPath);
-        if (files.length === 0) {
-          try {
-            fs.rmdirSync(fullPath);
-            issues.push({ path: entry.name + '/', action: 'deleted (empty rogue dir)' });
-          } catch (e) {
-            errors.push(`Failed to remove ${entry.name}/: ${e.message}`);
-          }
-        } else {
-          for (const file of files) {
-            const src = path.join(fullPath, file);
-            const dest = guessDestination(file);
-            if (dest) {
-              try {
-                const destPath = path.join(baseDir, dest, file);
-                fs.mkdirSync(path.join(baseDir, dest), { recursive: true });
-                fs.renameSync(src, destPath);
-                issues.push({ path: `${entry.name}/${file}`, action: `moved → ${dest}/${file}` });
-              } catch (e) {
-                errors.push(`Failed to move ${entry.name}/${file}: ${e.message}`);
-              }
-            } else {
-              try {
-                fs.unlinkSync(src);
-                issues.push({ path: `${entry.name}/${file}`, action: 'deleted (unknown type)' });
-              } catch (e) {
-                errors.push(`Failed to delete ${entry.name}/${file}: ${e.message}`);
-              }
-            }
-          }
-          try {
-            fs.rmdirSync(fullPath);
-            issues.push({ path: entry.name + '/', action: 'deleted (rogue dir cleared)' });
-          } catch {}
-        }
+        rogueItems.push({ type: 'dir', name: entry.name, children: safeReaddirAll(path.join(userDir, entry.name)) });
       }
     } else if (entry.isFile()) {
       if (!ALLOWED_FILES.has(entry.name) && !ALLOWED_PATTERNS.some(p => p.test(entry.name))) {
-        const dest = guessDestination(entry.name);
-        if (dest) {
-          try {
-            const destPath = path.join(baseDir, dest, entry.name);
-            fs.mkdirSync(path.join(baseDir, dest), { recursive: true });
-            fs.renameSync(fullPath, destPath);
-            issues.push({ path: entry.name, action: `moved → ${dest}/${entry.name}` });
-          } catch (e) {
-            errors.push(`Failed to move ${entry.name}: ${e.message}`);
-          }
-        } else {
-          try {
-            fs.unlinkSync(fullPath);
-            issues.push({ path: entry.name, action: 'deleted (unknown file at root)' });
-          } catch (e) {
-            errors.push(`Failed to delete ${entry.name}: ${e.message}`);
-          }
-        }
+        rogueItems.push({ type: 'file', name: entry.name });
       }
     }
   }
 
-  const dirFileRules = {
-    personality: ['.md'],
-    scripts: ['.js', '.sh'],
-    tests: ['.js', '.sh'],
-    commands: ['.md'],
-  };
-
-  for (const [dir, allowedExts] of Object.entries(dirFileRules)) {
-    const dirPath = path.join(baseDir, dir);
+  for (const [dir, allowedExts] of Object.entries(DIR_FILE_RULES)) {
+    const dirPath = path.join(userDir, dir);
     if (!fs.existsSync(dirPath)) continue;
-
-    const files = safeReaddir(dirPath);
-    for (const file of files) {
+    for (const file of safeReaddir(dirPath)) {
       const ext = path.extname(file);
       if (ext && !allowedExts.includes(ext)) {
-        const dest = guessDestination(file);
-        if (dest && dest !== dir) {
-          try {
-            const src = path.join(dirPath, file);
-            const destPath = path.join(baseDir, dest, file);
-            fs.mkdirSync(path.join(baseDir, dest), { recursive: true });
-            fs.renameSync(src, destPath);
-            issues.push({ path: `${dir}/${file}`, action: `moved → ${dest}/${file}` });
-          } catch (e) {
-            errors.push(`Failed to move ${dir}/${file}: ${e.message}`);
+        rogueItems.push({ type: 'misplaced', name: file, currentDir: dir });
+      }
+    }
+  }
+
+  return rogueItems;
+}
+
+/**
+ * @param {Array} rogueItems
+ * @param {object} claudeClient - Anthropic client instance
+ * @returns {Promise<Array<{path: string, action: string, dest?: string}>|null>}
+ */
+async function resolveWithLlm(rogueItems, claudeClient) {
+  const itemList = rogueItems.map(item => {
+    if (item.type === 'dir') {
+      return `- Directory "${item.name}/" containing: ${item.children.length ? item.children.join(', ') : '(empty)'}`;
+    }
+    if (item.type === 'misplaced') {
+      return `- File "${item.currentDir}/${item.name}" (wrong location for its type)`;
+    }
+    return `- File "${item.name}" at root level`;
+  }).join('\n');
+
+  const prompt = `You are organizing a workspace directory. The valid structure is:
+- personality/ — .md files (soul, personality config)
+- scripts/ — .js and .sh scripts
+- tests/ — test files (test-*.js, test_*.js, *.test.js)
+- commands/ — .md command definitions
+- apps/ — application subdirectories
+- logs/ — log files
+- assets/ — media and binary assets
+
+These items don't belong in their current location:
+${itemList}
+
+For each item, decide: "move" to a valid directory, or "delete" if truly rogue/irrelevant.
+Respond ONLY with a JSON array, no explanation:
+[{"path":"item-name","action":"move|delete","dest":"destination-dir"}]
+For directories use "dirname/", for misplaced files use "currentDir/filename".`;
+
+  const response = await claudeClient.messages.create({
+    model: 'claude-haiku-4-5-20251001',
+    max_tokens: 1024,
+    messages: [{ role: 'user', content: prompt }],
+  });
+
+  const text = response.content[0]?.text || '[]';
+  const match = text.match(/\[[\s\S]*\]/);
+  if (!match) return null;
+  try {
+    return JSON.parse(match[0]);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} userDir
+ * @param {Array} rogueItems
+ * @param {Array} decisions
+ * @returns {{issues: Array, errors: Array}}
+ */
+function applyDecisions(userDir, rogueItems, decisions) {
+  const issues = [];
+  const errors = [];
+
+  for (const decision of decisions) {
+    const item = rogueItems.find(r => {
+      if (r.type === 'dir') return decision.path === r.name + '/';
+      if (r.type === 'misplaced') return decision.path === `${r.currentDir}/${r.name}`;
+      return decision.path === r.name;
+    });
+    if (!item) continue;
+
+    const srcPath = item.type === 'misplaced'
+      ? path.join(userDir, item.currentDir, item.name)
+      : path.join(userDir, item.name);
+
+    if (decision.action === 'delete') {
+      try {
+        fs.rmSync(srcPath, { recursive: true, force: true });
+        issues.push({ path: decision.path, action: 'deleted' });
+      } catch (e) {
+        errors.push(`Failed to delete ${decision.path}: ${e.message}`);
+      }
+    } else if (decision.action === 'move' && decision.dest) {
+      const destDir = path.join(userDir, decision.dest);
+      const destPath = path.join(destDir, item.name);
+      try {
+        fs.mkdirSync(destDir, { recursive: true });
+        fs.renameSync(srcPath, destPath);
+        issues.push({ path: decision.path, action: `moved → ${decision.dest}/${item.name}` });
+      } catch (e) {
+        errors.push(`Failed to move ${decision.path}: ${e.message}`);
+      }
+    }
+  }
+
+  return { issues, errors };
+}
+
+/**
+ * @param {string} userDir
+ * @param {Array} rogueItems
+ * @returns {{issues: Array, errors: Array}}
+ */
+function applyHeuristics(userDir, rogueItems) {
+  const issues = [];
+  const errors = [];
+
+  for (const item of rogueItems) {
+    if (item.type === 'dir') {
+      const fullPath = path.join(userDir, item.name);
+      const files = safeReaddir(fullPath);
+
+      if (item.children.length === 0) {
+        try {
+          fs.rmSync(fullPath, { recursive: true, force: true });
+          issues.push({ path: item.name + '/', action: 'deleted (empty rogue dir)' });
+        } catch (e) {
+          errors.push(`Failed to remove ${item.name}/: ${e.message}`);
+        }
+      } else {
+        for (const file of files) {
+          const dest = guessDestination(file);
+          if (dest) {
+            try {
+              const destPath = path.join(userDir, dest, file);
+              fs.mkdirSync(path.join(userDir, dest), { recursive: true });
+              fs.renameSync(path.join(fullPath, file), destPath);
+              issues.push({ path: `${item.name}/${file}`, action: `moved → ${dest}/${file}` });
+            } catch (e) {
+              errors.push(`Failed to move ${item.name}/${file}: ${e.message}`);
+            }
+          } else {
+            try {
+              fs.unlinkSync(path.join(fullPath, file));
+              issues.push({ path: `${item.name}/${file}`, action: 'deleted (unknown type)' });
+            } catch (e) {
+              errors.push(`Failed to delete ${item.name}/${file}: ${e.message}`);
+            }
           }
         }
+        try {
+          fs.rmSync(fullPath, { recursive: true, force: true });
+          issues.push({ path: item.name + '/', action: 'deleted (rogue dir cleared)' });
+        } catch {}
+      }
+    } else if (item.type === 'file') {
+      const dest = guessDestination(item.name);
+      const fullPath = path.join(userDir, item.name);
+      if (dest) {
+        try {
+          const destPath = path.join(userDir, dest, item.name);
+          fs.mkdirSync(path.join(userDir, dest), { recursive: true });
+          fs.renameSync(fullPath, destPath);
+          issues.push({ path: item.name, action: `moved → ${dest}/${item.name}` });
+        } catch (e) {
+          errors.push(`Failed to move ${item.name}: ${e.message}`);
+        }
+      } else {
+        try {
+          fs.unlinkSync(fullPath);
+          issues.push({ path: item.name, action: 'deleted (unknown file at root)' });
+        } catch (e) {
+          errors.push(`Failed to delete ${item.name}: ${e.message}`);
+        }
+      }
+    } else if (item.type === 'misplaced') {
+      const dest = guessDestination(item.name);
+      if (dest && dest !== item.currentDir) {
+        const src = path.join(userDir, item.currentDir, item.name);
+        try {
+          const destPath = path.join(userDir, dest, item.name);
+          fs.mkdirSync(path.join(userDir, dest), { recursive: true });
+          fs.renameSync(src, destPath);
+          issues.push({ path: `${item.currentDir}/${item.name}`, action: `moved → ${dest}/${item.name}` });
+        } catch (e) {
+          errors.push(`Failed to move ${item.currentDir}/${item.name}: ${e.message}`);
+        }
       }
     }
   }
@@ -143,21 +258,30 @@ async function cleanWorkspace(userDir) {
   return { issues, errors };
 }
 
-function guessDestination(filename) {
-  const ext = path.extname(filename);
+/**
+ * @param {string} userDir
+ * @param {object|null} claudeClient - optional Anthropic client for LLM-based resolution
+ * @returns {Promise<{issues: Array, errors: Array}>}
+ */
+async function cleanWorkspace(userDir, claudeClient = null) {
+  const baseDir = userDir || OBOL_DIR;
+  if (!fs.existsSync(baseDir)) {
+    return { issues: [], errors: ['Directory does not exist'] };
+  }
 
-  // Test files go to tests/
-  if (filename.startsWith('test-') || filename.startsWith('test_')) return 'tests';
+  const rogueItems = scanWorkspace(baseDir);
+  if (rogueItems.length === 0) return { issues: [], errors: [] };
 
-  return FILE_RULES[ext] || null;
-}
+  if (claudeClient) {
+    try {
+      const decisions = await resolveWithLlm(rogueItems, claudeClient);
+      if (decisions) return applyDecisions(baseDir, rogueItems, decisions);
+    } catch (e) {
+      console.error('[clean] LLM resolution failed, falling back to heuristics:', e.message);
+    }
+  }
 
-function safeReaddir(dir) {
-  try {
-    return fs.readdirSync(dir).filter(f => {
-      try { return fs.statSync(path.join(dir, f)).isFile(); } catch { return false; }
-    });
-  } catch { return []; }
+  return applyHeuristics(baseDir, rogueItems);
 }
 
 module.exports = { cleanWorkspace };

package/src/telegram/commands/admin.js

@@ -28,7 +28,7 @@ function register(bot, config) {
     const { cleanWorkspace } = require('../../clean');
     await ctx.replyWithChatAction('typing');
     try {
-      const result = await cleanWorkspace(tenant.userDir);
+      const result = await cleanWorkspace(tenant.userDir, tenant.claude.client);
       if (result.issues.length === 0) {
         await ctx.reply('✨ Workspace is clean. Nothing out of place.');
       } else {

package/src/telegram/handlers/callbacks.js

@@ -13,6 +13,7 @@ function registerCallbackHandler(bot, { config, pendingAsks, getTenant }) {
       const tenant = await getTenant(userId, config);
       const stopped = tenant?.claude?.stopChat(chatId);
       await answer({ text: stopped ? 'Stopping...' : 'Nothing to stop' });
+      ctx.editMessageReplyMarkup({ inline_keyboard: [] }).catch(() => {});
       return;
     }
 
@@ -22,6 +23,7 @@ function registerCallbackHandler(bot, { config, pendingAsks, getTenant }) {
       const tenant = await getTenant(userId, config);
       const stopped = tenant?.claude?.forceStopChat(chatId);
       await answer({ text: stopped ? 'Force stopped' : 'Nothing to stop' });
+      ctx.editMessageReplyMarkup({ inline_keyboard: [] }).catch(() => {});
       return;
     }
 
@@ -107,7 +109,7 @@ function registerCallbackHandler(bot, { config, pendingAsks, getTenant }) {
     clearTimeout(pending.timer);
     pendingAsks.delete(askId);
     const confirmHtml = markdownToTelegramHtml(`${ctx.callbackQuery.message.text}\n\n✓ _${selected}_`);
-    ctx.editMessageText(confirmHtml, { parse_mode: 'HTML' }).catch(() => {});
+    ctx.editMessageText(confirmHtml, { parse_mode: 'HTML', reply_markup: { inline_keyboard: [] } }).catch(() => {});
     pending.resolve(selected);
   });
 }