@agile-vibe-coding/avc 0.3.4 → 0.4.0

package/cli/worktree-runner.js

@@ -14,6 +14,8 @@ import path from 'path';
 import { execSync, execFileSync } from 'child_process';
 import { LLMProvider } from './llm-provider.js';
 import { loadAgent } from './agent-loader.js';
+import { buildToolDefinitions, executeTool, summarizeToolCall, FileTracker } from './worktree-tools.js';
+import { TokenTracker } from './token-tracker.js';
 import { fileURLToPath } from 'url';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -66,6 +68,10 @@ export class WorktreeRunner {
     this._maxIterations = ceremony?.maxValidationIterations ?? 3;
     this._acceptanceThreshold = ceremony?.acceptanceThreshold ?? 80;
     this._stageProviders = {};
+
+    // Token tracking for cost dashboard
+    this.tokenTracker = new TokenTracker(this.avcPath);
+    this.tokenTracker.init();
   }
 
   /**
@@ -125,33 +131,36 @@ export class WorktreeRunner {
       if (cancelledCheck?.()) throw new Error('CANCELLED');
       const context = this.readDocChain();
 
-      // 3. Implement code via LLM
-      progressCallback?.('Implementing code with AI agent...');
+      // 3. Run agentic tool-calling loop
+      progressCallback?.('Starting agentic implementation loop...');
       if (cancelledCheck?.()) throw new Error('CANCELLED');
-      await this.implementCode(context, progressCallback);
+      const fileTracker = await this.executeAgentLoop(context, progressCallback, cancelledCheck);
 
-      // 4. Run tests
-      progressCallback?.('Running tests...');
-      if (cancelledCheck?.()) throw new Error('CANCELLED');
-      const testResult = this.runTests();
+      // 4. Write file registry and test results
+      this._updateFileRegistry(fileTracker);
+      this._updateTestResults(fileTracker);
 
-      if (!testResult.passed) {
-        progressCallback?.(`Tests failed: ${testResult.summary}`);
-        this.cleanup();
-        return { success: false, error: `Tests failed: ${testResult.summary}` };
-      }
+      // 5. Finalize token tracking
+      try { this.tokenTracker.finalizeRun('run'); } catch {}
 
-      // 5. Commit and merge
-      progressCallback?.('Committing and merging to main...');
+      // 6. Commit in worktree (do NOT merge — leave for human review)
+      progressCallback?.('Committing changes in worktree...');
       if (cancelledCheck?.()) throw new Error('CANCELLED');
-      this.commitAndMerge();
+      this.commitInWorktree();
 
-      // 6. Cleanup
-      progressCallback?.('Cleaning up worktree...');
-      this.cleanup();
+      // 5. Leave worktree in place for review
+      progressCallback?.(`Code ready for review in worktree: ${this.worktreePath}`);
+      progressCallback?.(`Branch: ${this.branchName}`);
 
-      return { success: true };
+      return {
+        success: true,
+        review: true,
+        worktreePath: this.worktreePath,
+        branchName: this.branchName,
+      };
     } catch (err) {
+      // Finalize token tracking even on failure (tokens were spent)
+      try { this.tokenTracker.finalizeRun('run'); } catch {}
       // Always cleanup on failure
       try { this.cleanup(); } catch {}
 
@@ -162,6 +171,212 @@ export class WorktreeRunner {
     }
   }
 
+  /**
+   * Agentic tool-calling loop — the model calls tools iteratively until it decides it's done.
+   * Follows the Claude Code pattern: while(tool_calls) → execute → feed back → repeat.
+   */
+  async executeAgentLoop(context, progressCallback, cancelledCheck = null) {
+    const provider = await this._getStageProvider('code-generation');
+    const agentInstructions = loadAgent('code-implementer.md');
+    const tools = buildToolDefinitions();
+    const acceptance = this._readAcceptanceCriteria();
+    const tracker = new FileTracker();
+
+    const userPrompt = [
+      `## Hierarchy Prefix\n${this.prefix}`,
+      `## Task ID\n${this.taskId}`,
+      `## Acceptance Criteria\n${acceptance.map((ac, i) => `${i + 1}. ${ac}`).join('\n')}`,
+      `## Documentation Chain\n\n${context}`,
+    ].join('\n\n');
+
+    const messages = [
+      { role: 'system', content: agentInstructions },
+      { role: 'user', content: userPrompt },
+    ];
+
+    const MAX_ITERATIONS = 50;
+    let iteration = 0;
+
+    while (iteration < MAX_ITERATIONS) {
+      iteration++;
+      if (cancelledCheck?.()) throw new Error('CANCELLED');
+
+      this.debug(`Agent loop iteration ${iteration}/${MAX_ITERATIONS}`);
+      const response = await provider.chat(messages, { tools });
+
+      // If the model returned text, show it
+      if (response.content) {
+        progressCallback?.(`Agent: ${response.content.slice(0, 200)}`);
+      }
+
+      // If no tool calls, the agent is done
+      if (!response.toolCalls || response.toolCalls.length === 0) {
+        this.debug(`Agent loop complete after ${iteration} iterations (model stopped)`);
+        progressCallback?.(`Implementation complete after ${iteration} iterations.`);
+        break;
+      }
+
+      // Add assistant message with tool calls to history
+      messages.push({
+        role: 'assistant',
+        content: response.content || '',
+        toolCalls: response.toolCalls,
+      });
+
+      // Execute each tool call and add results to history
+      for (const call of response.toolCalls) {
+        if (cancelledCheck?.()) throw new Error('CANCELLED');
+
+        const summary = summarizeToolCall(call.name, call.arguments);
+        progressCallback?.(`[${call.name}] ${summary}`);
+
+        const result = executeTool(this.worktreePath, call.name, call.arguments, 120_000, tracker);
+
+        messages.push({
+          role: 'tool',
+          toolCallId: call.id,
+          toolName: call.name, // needed for Gemini
+          content: typeof result === 'string' ? result : JSON.stringify(result),
+        });
+
+        this.debug(`Tool: ${call.name}(${summary}) → ${String(result).slice(0, 200)}`);
+      }
+    }
+
+    if (iteration >= MAX_ITERATIONS) {
+      progressCallback?.(`Warning: agent loop hit max iterations (${MAX_ITERATIONS}).`);
+    }
+
+    return tracker;
+  }
+
+  /**
+   * Update the centralized file registry and the task's work.json with file tracking data.
+   * Registry: .avc/project/file-registry.json — bidirectional mapping of files ↔ tasks.
+   * work.json: adds a `files` object with created/edited/deleted arrays.
+   */
+  _updateFileRegistry(tracker) {
+    if (!tracker || tracker.operations.length === 0) return;
+
+    const byAction = tracker.getByAction();
+    const allFiles = [...byAction.created, ...byAction.edited];
+
+    // 1. Update task work.json with files summary
+    try {
+      const taskWorkJsonPath = this._findWorkJsonPath(this.taskId);
+      if (taskWorkJsonPath && fs.existsSync(taskWorkJsonPath)) {
+        const workJson = JSON.parse(fs.readFileSync(taskWorkJsonPath, 'utf8'));
+        workJson.files = byAction;
+        fs.writeFileSync(taskWorkJsonPath, JSON.stringify(workJson, null, 2), 'utf8');
+        this.debug('Task work.json updated with files', byAction);
+      }
+    } catch (err) {
+      this.debug('Failed to update task work.json with files', { error: err.message });
+    }
+
+    // 2. Update centralized file registry
+    try {
+      const registryPath = path.join(this.avcPath, 'project', 'file-registry.json');
+      let registry = { version: '1.0', files: {}, tasks: {} };
+      if (fs.existsSync(registryPath)) {
+        try { registry = JSON.parse(fs.readFileSync(registryPath, 'utf8')); } catch {}
+      }
+
+      // Update files → tasks mapping
+      for (const op of tracker.getSummary()) {
+        if (!registry.files[op.path]) {
+          registry.files[op.path] = { createdBy: null, tasks: [], operations: [] };
+        }
+        const entry = registry.files[op.path];
+        if (op.firstAction === 'created' && !entry.createdBy) {
+          entry.createdBy = this.taskId;
+        }
+        if (!entry.tasks.includes(this.taskId)) {
+          entry.tasks.push(this.taskId);
+        }
+        entry.operations.push({
+          taskId: this.taskId,
+          action: op.lastAction,
+          timestamp: op.lastTimestamp,
+        });
+      }
+
+      // Update tasks → files mapping
+      registry.tasks[this.taskId] = {
+        files: allFiles,
+        ...byAction,
+        completedAt: new Date().toISOString(),
+      };
+
+      fs.writeFileSync(registryPath, JSON.stringify(registry, null, 2), 'utf8');
+      this.debug('File registry updated', { files: allFiles.length, operations: tracker.operations.length });
+    } catch (err) {
+      this.debug('Failed to update file registry', { error: err.message });
+    }
+  }
+
+  /**
+   * Find work.json path for a task ID (tries flat first, then nested).
+   */
+  _findWorkJsonPath(taskId) {
+    // Flat path (tasks written by seed-processor)
+    const flatPath = path.join(this.avcPath, 'project', taskId, 'work.json');
+    if (fs.existsSync(flatPath)) return flatPath;
+
+    // Nested path (epics/stories)
+    const idParts = taskId.replace('context-', '').split('-');
+    let dir = path.join(this.avcPath, 'project');
+    let current = 'context';
+    for (const part of idParts) {
+      current += `-${part}`;
+      dir = path.join(dir, current);
+    }
+    const nestedPath = path.join(dir, 'work.json');
+    if (fs.existsSync(nestedPath)) return nestedPath;
+
+    return null;
+  }
+
+  /**
+   * Store test results and mark acceptance criteria as passed/failed in work.json.
+   * Reads the last command output from the tracker (typically the final `npm test` run)
+   * and stores it alongside AC pass status for the kanban card review display.
+   */
+  _updateTestResults(tracker) {
+    try {
+      const taskWorkJsonPath = this._findWorkJsonPath(this.taskId);
+      if (!taskWorkJsonPath || !fs.existsSync(taskWorkJsonPath)) return;
+
+      const workJson = JSON.parse(fs.readFileSync(taskWorkJsonPath, 'utf8'));
+      const lastTest = tracker.getLastCommandOutput();
+
+      // Store test output for review display
+      workJson.testResults = {
+        passed: lastTest ? lastTest.exitCode === 0 : false,
+        command: lastTest?.command || null,
+        output: lastTest?.output?.slice(-2000) || null, // last 2KB for display
+        timestamp: lastTest?.timestamp || new Date().toISOString(),
+      };
+
+      // Mark all ACs as passed if tests passed (the agent verified them all before stopping)
+      if (lastTest?.exitCode === 0 && Array.isArray(workJson.acceptance)) {
+        workJson.acceptanceStatus = workJson.acceptance.map((ac, i) => ({
+          criterion: ac,
+          passed: true,
+          index: i + 1,
+        }));
+      }
+
+      fs.writeFileSync(taskWorkJsonPath, JSON.stringify(workJson, null, 2), 'utf8');
+      this.debug('Test results written to work.json', {
+        passed: workJson.testResults.passed,
+        acsPassed: workJson.acceptanceStatus?.filter(a => a.passed).length ?? 0,
+      });
+    } catch (err) {
+      this.debug('Failed to update test results', { error: err.message });
+    }
+  }
+
   /**
    * Create a new git worktree for the task.
    */
@@ -196,6 +411,17 @@ export class WorktreeRunner {
 
     // Create new worktree with branch
     git(['worktree', 'add', this.worktreePath, '-b', this.branchName], this.projectRoot);
+
+    // Remove directories that should not be in the worktree
+    const excludeDirs = ['.avc', 'node_modules', '.env'];
+    for (const dir of excludeDirs) {
+      const dirPath = path.join(this.worktreePath, dir);
+      if (fs.existsSync(dirPath)) {
+        fs.rmSync(dirPath, { recursive: true, force: true });
+        this.debug(`Removed ${dir} from worktree`);
+      }
+    }
+
     this.debug('Worktree created', { path: this.worktreePath, branch: this.branchName });
   }
 
@@ -294,7 +520,14 @@ export class WorktreeRunner {
     const provider = stageConfig.provider || this._defaultProvider;
     const model = stageConfig.model || this._defaultModel;
 
-    const instance = await LLMProvider.create(provider, model);
+    const resolved = await LLMProvider.resolveAvailableProvider(provider, model);
+    if (resolved.fellBack) {
+      this.debug(`Provider fallback for ${stageName}: ${provider}→${resolved.provider}`);
+    }
+
+    const instance = await LLMProvider.create(resolved.provider, resolved.model);
+    // Register token tracking callback
+    instance.onCall((delta) => this.tokenTracker.addIncremental(`run-${stageName}`, delta));
     this._stageProviders[key] = instance;
     return instance;
   }
@@ -583,28 +816,35 @@ export class WorktreeRunner {
   /**
    * Commit changes in the worktree and merge to the main branch.
    */
-  commitAndMerge() {
-    // Stage all changes
+  /**
+   * Commit all changes in the worktree (does NOT merge to main).
+   * Called after tests pass — the worktree stays in place for human review.
+   */
+  commitInWorktree() {
     git(['add', '-A'], this.worktreePath);
 
-    // Check if there's anything to commit
     const status = git(['status', '--porcelain'], this.worktreePath);
     if (!status) {
       this.debug('No changes to commit');
       return;
     }
 
-    // Commit
     const commitMsg = `feat(${this.taskId}): implement task\n\nGenerated by AVC WorktreeRunner`;
     git(['commit', '-m', commitMsg], this.worktreePath);
     this.debug('Committed in worktree');
+  }
 
+  /**
+   * Merge the worktree branch into main and clean up.
+   * Called AFTER human review approves the code (status: implemented → completed).
+   * Can be invoked via API or CLI.
+   */
+  mergeAndCleanup() {
     // Determine the main branch name
     let mainBranch = 'main';
     try {
       mainBranch = git(['symbolic-ref', '--short', 'HEAD'], this.projectRoot);
     } catch {
-      // If HEAD is detached, try common branch names
       try { git(['rev-parse', '--verify', 'main'], this.projectRoot); mainBranch = 'main'; } catch {
         try { git(['rev-parse', '--verify', 'master'], this.projectRoot); mainBranch = 'master'; } catch {}
       }
@@ -615,10 +855,12 @@ export class WorktreeRunner {
       git(['merge', '--no-ff', this.branchName, '-m', `Merge ${this.branchName}: implement ${this.taskId}`], this.projectRoot);
       this.debug('Merged to main', { mainBranch });
     } catch (err) {
-      // Merge conflict — abort and report
       try { git(['merge', '--abort'], this.projectRoot); } catch {}
       throw new Error(`Merge conflict: ${err.message}`);
     }
+
+    // Cleanup worktree and branch
+    this.cleanup();
   }
 
   /**

package/cli/worktree-tools.js

@@ -0,0 +1,322 @@
+/**
+ * worktree-tools.js — Sandboxed tool definitions and executors for the agentic Run ceremony.
+ *
+ * All file operations are restricted to the worktree path.
+ * Shell commands execute with cwd set to the worktree.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+import { globSync } from 'glob';
+
+/**
+ * File operation tracker — records all write/edit/delete operations for the file registry.
+ * Caller creates one per agent loop and reads it after the loop completes.
+ */
+export class FileTracker {
+  constructor() {
+    this.operations = []; // { action: 'created'|'edited'|'deleted', path, timestamp }
+  }
+
+  record(action, filePath) {
+    this.operations.push({ action, path: filePath, timestamp: new Date().toISOString() });
+  }
+
+  /** Get the last run_command output (typically the final test run). */
+  getLastCommandOutput() {
+    return this._lastCommandOutput || null;
+  }
+
+  /** Record a command output (called by executeTool for run_command). */
+  recordCommandOutput(command, output, exitCode) {
+    this._lastCommandOutput = { command, output, exitCode, timestamp: new Date().toISOString() };
+  }
+
+  /** Get deduplicated file list with final action per file. */
+  getSummary() {
+    const fileMap = {};
+    for (const op of this.operations) {
+      if (!fileMap[op.path]) {
+        fileMap[op.path] = { path: op.path, actions: [], firstAction: op.action, firstTimestamp: op.timestamp };
+      }
+      fileMap[op.path].actions.push(op.action);
+      fileMap[op.path].lastAction = op.action;
+      fileMap[op.path].lastTimestamp = op.timestamp;
+    }
+    return Object.values(fileMap);
+  }
+
+  /** Get arrays grouped by action type. */
+  getByAction() {
+    const created = [], edited = [], deleted = [];
+    const seen = new Set();
+    // Walk in reverse to get final state per file
+    for (let i = this.operations.length - 1; i >= 0; i--) {
+      const op = this.operations[i];
+      if (seen.has(op.path)) continue;
+      seen.add(op.path);
+      if (op.action === 'created') created.push(op.path);
+      else if (op.action === 'edited') edited.push(op.path);
+      else if (op.action === 'deleted') deleted.push(op.path);
+    }
+    return { created: created.sort(), edited: edited.sort(), deleted: deleted.sort() };
+  }
+}
+
+/**
+ * Validate that a file path resolves inside the worktree (no escaping via ../ or symlinks).
+ */
+function safePath(worktreePath, filePath) {
+  const resolved = path.resolve(worktreePath, filePath);
+  if (!resolved.startsWith(path.resolve(worktreePath) + path.sep) && resolved !== path.resolve(worktreePath)) {
+    throw new Error(`Path "${filePath}" escapes worktree boundary`);
+  }
+  return resolved;
+}
+
+/**
+ * Build the tool definitions array in OpenAI-compatible function-calling schema.
+ * These are sent to the LLM so it knows what tools are available.
+ */
+export function buildToolDefinitions() {
+  return [
+    {
+      type: 'function',
+      function: {
+        name: 'read_file',
+        description: 'Read the contents of a file in the worktree. Returns the file content as a string.',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: { type: 'string', description: 'Relative file path from worktree root' },
+          },
+          required: ['path'],
+        },
+      },
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'write_file',
+        description: 'Create or overwrite a file in the worktree with the given content.',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: { type: 'string', description: 'Relative file path from worktree root' },
+            content: { type: 'string', description: 'Full file content to write' },
+          },
+          required: ['path', 'content'],
+        },
+      },
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'edit_file',
+        description: 'Replace a specific string in a file. The old_string must match exactly (including whitespace). Use for targeted edits to existing files.',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: { type: 'string', description: 'Relative file path from worktree root' },
+            old_string: { type: 'string', description: 'Exact string to find (must be unique in the file)' },
+            new_string: { type: 'string', description: 'Replacement string' },
+          },
+          required: ['path', 'old_string', 'new_string'],
+        },
+      },
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'delete_file',
+        description: 'Delete a file from the worktree.',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: { type: 'string', description: 'Relative file path from worktree root' },
+          },
+          required: ['path'],
+        },
+      },
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'list_files',
+        description: 'List files in the worktree matching a glob pattern. Returns newline-separated file paths.',
+        parameters: {
+          type: 'object',
+          properties: {
+            pattern: { type: 'string', description: 'Glob pattern (e.g., "src/**/*.js", "*.json"). Defaults to "**/*" if omitted.' },
+          },
+        },
+      },
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'run_command',
+        description: 'Execute a shell command in the worktree directory. Returns stdout+stderr. Use for running tests, installing packages, compiling, etc.',
+        parameters: {
+          type: 'object',
+          properties: {
+            command: { type: 'string', description: 'Shell command to execute' },
+          },
+          required: ['command'],
+        },
+      },
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'search_code',
+        description: 'Search for a regex pattern in worktree files. Returns matching lines with file paths and line numbers.',
+        parameters: {
+          type: 'object',
+          properties: {
+            pattern: { type: 'string', description: 'Regex pattern to search for' },
+            glob: { type: 'string', description: 'File glob to restrict search (e.g., "*.js"). Defaults to all files.' },
+          },
+          required: ['pattern'],
+        },
+      },
+    },
+  ];
+}
+
+/**
+ * Execute a tool call within the worktree sandbox.
+ * @param {string} worktreePath - Absolute path to the worktree root
+ * @param {string} toolName - Tool name
+ * @param {object} args - Tool arguments
+ * @param {number} commandTimeout - Timeout for shell commands in ms (default 120s)
+ * @returns {string} Tool result as a string
+ */
+export function executeTool(worktreePath, toolName, args, commandTimeout = 120_000, tracker = null) {
+  try {
+    switch (toolName) {
+      case 'read_file': {
+        const filePath = safePath(worktreePath, args.path);
+        if (!fs.existsSync(filePath)) return `Error: file not found: ${args.path}`;
+        const stat = fs.statSync(filePath);
+        if (stat.size > 500_000) return `Error: file too large (${stat.size} bytes, max 500KB)`;
+        return fs.readFileSync(filePath, 'utf8');
+      }
+
+      case 'write_file': {
+        const filePath = safePath(worktreePath, args.path);
+        const existed = fs.existsSync(filePath);
+        const dir = path.dirname(filePath);
+        if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(filePath, args.content, 'utf8');
+        tracker?.record(existed ? 'edited' : 'created', args.path);
+        return `Written: ${args.path} (${args.content.length} bytes)`;
+      }
+
+      case 'edit_file': {
+        const filePath = safePath(worktreePath, args.path);
+        if (!fs.existsSync(filePath)) return `Error: file not found: ${args.path}`;
+        const content = fs.readFileSync(filePath, 'utf8');
+        if (!content.includes(args.old_string)) {
+          return `Error: old_string not found in ${args.path}. Make sure it matches exactly (including whitespace).`;
+        }
+        const occurrences = content.split(args.old_string).length - 1;
+        if (occurrences > 1) {
+          return `Error: old_string found ${occurrences} times in ${args.path}. It must be unique. Provide more surrounding context.`;
+        }
+        const newContent = content.replace(args.old_string, args.new_string);
+        fs.writeFileSync(filePath, newContent, 'utf8');
+        tracker?.record('edited', args.path);
+        return `Edited: ${args.path}`;
+      }
+
+      case 'delete_file': {
+        const filePath = safePath(worktreePath, args.path);
+        if (!fs.existsSync(filePath)) return `Error: file not found: ${args.path}`;
+        fs.unlinkSync(filePath);
+        tracker?.record('deleted', args.path);
+        return `Deleted: ${args.path}`;
+      }
+
+      case 'list_files': {
+        const pattern = args.pattern || '**/*';
+        const files = globSync(pattern, {
+          cwd: worktreePath,
+          nodir: true,
+          ignore: ['node_modules/**', '.git/**'],
+        });
+        if (files.length === 0) return '(no files match)';
+        return files.sort().join('\n');
+      }
+
+      case 'run_command': {
+        try {
+          const output = execSync(args.command, {
+            cwd: worktreePath,
+            encoding: 'utf8',
+            timeout: commandTimeout,
+            maxBuffer: 1024 * 1024,
+            stdio: ['pipe', 'pipe', 'pipe'],
+          });
+          tracker?.recordCommandOutput(args.command, output || '(no output)', 0);
+          return output || '(no output)';
+        } catch (err) {
+          const stdout = err.stdout || '';
+          const stderr = err.stderr || '';
+          const combined = `Exit code ${err.status ?? 1}\n${stdout}\n${stderr}`.trim();
+          tracker?.recordCommandOutput(args.command, combined, err.status ?? 1);
+          return combined;
+        }
+      }
+
+      case 'search_code': {
+        const fileGlob = args.glob || '**/*';
+        const files = globSync(fileGlob, {
+          cwd: worktreePath,
+          nodir: true,
+          ignore: ['node_modules/**', '.git/**'],
+        });
+        const regex = new RegExp(args.pattern, 'gm');
+        const results = [];
+        for (const file of files) {
+          const filePath = path.join(worktreePath, file);
+          try {
+            const content = fs.readFileSync(filePath, 'utf8');
+            const lines = content.split('\n');
+            for (let i = 0; i < lines.length; i++) {
+              if (regex.test(lines[i])) {
+                results.push(`${file}:${i + 1}: ${lines[i]}`);
+              }
+              regex.lastIndex = 0; // reset for global regex
+            }
+          } catch { /* skip binary/unreadable files */ }
+        }
+        if (results.length === 0) return '(no matches)';
+        if (results.length > 100) return results.slice(0, 100).join('\n') + `\n... (${results.length - 100} more matches)`;
+        return results.join('\n');
+      }
+
+      default:
+        return `Error: unknown tool "${toolName}"`;
+    }
+  } catch (err) {
+    return `Error: ${err.message}`;
+  }
+}
+
+/**
+ * Summarize a tool call for progress logging (one-line description).
+ */
+export function summarizeToolCall(toolName, args) {
+  switch (toolName) {
+    case 'read_file':    return args.path;
+    case 'write_file':   return `${args.path} (${args.content?.length ?? 0} bytes)`;
+    case 'edit_file':    return args.path;
+    case 'delete_file':  return args.path;
+    case 'list_files':   return args.pattern || '**/*';
+    case 'run_command':  return args.command?.slice(0, 80);
+    case 'search_code':  return `/${args.pattern}/ in ${args.glob || '*'}`;
+    default:             return toolName;
+  }
+}