vellum 0.2.1 → 0.2.7

package/src/tools/claude-code/claude-code.ts

@@ -3,6 +3,7 @@ import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
 import type { ToolDefinition } from '../../providers/types.js';
 import { getConfig } from '../../config/loader.js';
 import { getLogger } from '../../util/logger.js';
+import { truncate } from '../../util/truncate.js';
 import { getProfilePolicy } from '../../swarm/worker-backend.js';
 import type { WorkerProfile } from '../../swarm/worker-backend.js';
 
@@ -22,6 +23,30 @@ const APPROVAL_REQUIRED_TOOLS = new Set([
 
 const VALID_PROFILES: readonly WorkerProfile[] = ['general', 'researcher', 'coder', 'reviewer'];
 
+// Maximum nesting depth for Claude Code subprocesses.
+// Depth 0 = top-level assistant, depth 1 = first subprocess, etc.
+const MAX_CLAUDE_CODE_DEPTH = 1;
+const DEPTH_ENV_VAR = 'VELLUM_CLAUDE_CODE_DEPTH';
+
+function summarizeToolInput(toolName: string, input: Record<string, unknown>): string {
+  // Extract the most relevant field for each tool type
+  const name = toolName.toLowerCase();
+  if (name === 'bash') return String(input.command ?? '');
+  if (name === 'read' || name === 'file_read') return String(input.file_path ?? input.path ?? '');
+  if (name === 'edit' || name === 'file_edit') return String(input.file_path ?? input.path ?? '');
+  if (name === 'write' || name === 'file_write') return String(input.file_path ?? input.path ?? '');
+  if (name === 'glob') return String(input.pattern ?? '');
+  if (name === 'grep') return String(input.pattern ?? '');
+  if (name === 'websearch' || name === 'web_search') return String(input.query ?? '');
+  if (name === 'webfetch' || name === 'web_fetch') return String(input.url ?? '');
+  if (name === 'task') return String(input.description ?? '');
+  // Fallback: first string value
+  for (const val of Object.values(input)) {
+    if (typeof val === 'string' && val.length > 0 && val.length < 200) return val;
+  }
+  return '';
+}
+
 export const claudeCodeTool: Tool = {
   name: 'claude_code',
   description: 'Delegate a coding task to Claude Code, an AI-powered coding agent that can read, write, and edit files, run shell commands, and perform complex multi-step software engineering tasks autonomously.',
@@ -108,7 +133,10 @@ export const claudeCodeTool: Tool = {
 
     const { query } = sdkModule;
 
-    log.info({ prompt: prompt.slice(0, 100), workingDir, model, resume: !!resumeSessionId }, 'Starting Claude Code session');
+    // Collect stderr output from the Claude Code subprocess for debugging
+    const stderrLines: string[] = [];
+
+    log.info({ prompt: truncate(prompt, 100, ''), workingDir, model, resume: !!resumeSessionId }, 'Starting Claude Code session');
 
     // Build the canUseTool callback, enforcing profile-based restrictions
     const canUseTool: import('@anthropic-ai/claude-agent-sdk').CanUseTool = async (toolName, toolInput, _options) => {
@@ -151,6 +179,26 @@ export const claudeCodeTool: Tool = {
       }
     };
 
+    // Enforce nesting depth limit to prevent infinite recursion.
+    const currentDepth = parseInt(process.env[DEPTH_ENV_VAR] ?? '0', 10);
+    if (currentDepth >= MAX_CLAUDE_CODE_DEPTH) {
+      log.warn({ currentDepth, max: MAX_CLAUDE_CODE_DEPTH }, 'Claude Code nesting depth exceeded');
+      return {
+        content: `Error: Claude Code nesting depth exceeded (depth ${currentDepth}, max ${MAX_CLAUDE_CODE_DEPTH}). Cannot spawn another Claude Code subprocess.`,
+        isError: true,
+      };
+    }
+
+    // Build a clean env for the subprocess. Strip the SDK's own nesting guard
+    // (CLAUDECODE) so it can launch, but set our depth counter to enforce our limit.
+    const subprocessEnv: Record<string, string | undefined> = {
+      ...process.env,
+      ANTHROPIC_API_KEY: apiKey,
+      [DEPTH_ENV_VAR]: String(currentDepth + 1),
+    };
+    delete subprocessEnv.CLAUDECODE;
+    delete subprocessEnv.CLAUDE_CODE_ENTRYPOINT;
+
     // Build query options
     const queryOptions: import('@anthropic-ai/claude-agent-sdk').Options = {
       cwd: workingDir,
@@ -158,27 +206,47 @@ export const claudeCodeTool: Tool = {
       canUseTool,
       permissionMode: 'default',
       allowedTools: [...AUTO_APPROVE_TOOLS],
-      env: {
-        ...process.env,
-        ANTHROPIC_API_KEY: apiKey,
-      },
+      env: subprocessEnv,
       maxTurns: 50,
       persistSession: true,
+      stderr: (data: string) => {
+        const trimmed = data.trimEnd();
+        if (trimmed) {
+          stderrLines.push(trimmed);
+          log.debug({ stderr: trimmed }, 'Claude Code subprocess stderr');
+        }
+      },
     };
 
     if (resumeSessionId) {
       queryOptions.resume = resumeSessionId;
     }
 
+    // Declared outside try so the catch block can emit a final tool_complete on error.
+    let lastSubToolName: string | null = null;
+
     try {
       const conversation = query({ prompt, options: queryOptions });
       let resultText = '';
       let sessionId = '';
       let hasError = false;
 
+      // Track tool_use_id → {name, inputSummary} for enriching progress events.
+      const toolUseIdInfo = new Map<string, { name: string; inputSummary: string }>();
+      // Track tool_use_ids that we've already emitted tool_start for (to avoid duplicates).
+      const emittedToolUseIds = new Set<string>();
+      // Track the currently active tool_use_id from tool_progress events.
+      let activeToolUseId: string | null = null;
+
       for await (const message of conversation) {
         switch (message.type) {
           case 'assistant': {
+            // Check for SDK-level errors on the assistant message
+            if (message.error) {
+              log.error({ error: message.error, sessionId: message.session_id }, 'Claude Code assistant message error');
+              hasError = true;
+              resultText += `\n\n[Claude Code error: ${message.error}]`;
+            }
             // Extract text from assistant messages
             if (message.message?.content) {
               for (const block of message.message.content) {
@@ -186,29 +254,141 @@ export const claudeCodeTool: Tool = {
                   context.onOutput?.(block.text);
                   resultText += block.text;
                 }
+                if (block.type === 'tool_use') {
+                  // Capture info keyed by tool_use_id for enriching tool_progress events.
+                  const inputSummary = summarizeToolInput(block.name, block.input as Record<string, unknown>);
+                  toolUseIdInfo.set(block.id, { name: block.name, inputSummary });
+
+                  // Emit tool_start if we haven't already (tool_progress may have fired first).
+                  // NOTE: Do NOT emit tool_complete for the previous tool here. An assistant
+                  // message may contain multiple tool_use blocks (parallel tool use) and none
+                  // of them have executed yet at this point. Completions are handled by
+                  // tool_use_summary and tool_progress events.
+                  if (!emittedToolUseIds.has(block.id)) {
+                    context.onOutput?.(JSON.stringify({
+                      subType: 'tool_start',
+                      subToolName: block.name,
+                      subToolInput: inputSummary,
+                      subToolId: block.id,
+                    }));
+                    emittedToolUseIds.add(block.id);
+                    lastSubToolName = block.name;
+                    activeToolUseId = block.id;
+                  }
+                }
               }
             }
             sessionId = message.session_id;
             break;
           }
+          case 'tool_progress': {
+            // The SDK fires tool_progress periodically DURING tool execution.
+            // This is our primary signal for live sub-tool progress.
+            const toolUseId = message.tool_use_id;
+            const toolName = message.tool_name;
+            sessionId = message.session_id;
+
+            // Record tool name if we don't have it yet (tool_progress fires before assistant sometimes).
+            if (!toolUseIdInfo.has(toolUseId)) {
+              toolUseIdInfo.set(toolUseId, { name: toolName, inputSummary: '' });
+            }
+
+            if (!emittedToolUseIds.has(toolUseId)) {
+              // New tool — mark previous as complete and emit tool_start.
+              if (lastSubToolName && activeToolUseId !== toolUseId) {
+                context.onOutput?.(JSON.stringify({
+                  subType: 'tool_complete',
+                  subToolName: lastSubToolName,
+                  subToolId: activeToolUseId,
+                }));
+              }
+              const inputSummary = toolUseIdInfo.get(toolUseId)?.inputSummary ?? '';
+              context.onOutput?.(JSON.stringify({
+                subType: 'tool_start',
+                subToolName: toolName,
+                subToolInput: inputSummary,
+                subToolId: toolUseId,
+              }));
+              emittedToolUseIds.add(toolUseId);
+              lastSubToolName = toolName;
+            }
+            activeToolUseId = toolUseId;
+            break;
+          }
+          case 'tool_use_summary': {
+            // The SDK fires tool_use_summary after tool execution with a summary
+            // and the IDs of tools that were executed.
+            sessionId = message.session_id;
+            for (const completedId of message.preceding_tool_use_ids) {
+              const info = toolUseIdInfo.get(completedId);
+              const completedName: string | null = info?.name ?? lastSubToolName;
+              if (completedName && emittedToolUseIds.has(completedId)) {
+                context.onOutput?.(JSON.stringify({
+                  subType: 'tool_complete',
+                  subToolName: completedName,
+                  subToolId: completedId,
+                }));
+                if (lastSubToolName === completedName) {
+                  lastSubToolName = null;
+                }
+              }
+              // Prune completed entries to keep memory flat across long sessions.
+              toolUseIdInfo.delete(completedId);
+              emittedToolUseIds.delete(completedId);
+            }
+            activeToolUseId = null;
+            break;
+          }
           case 'result': {
+            // Mark the final sub-tool as complete (flag error if the session failed).
+            if (lastSubToolName) {
+              const isFailure = message.subtype !== 'success';
+              context.onOutput?.(JSON.stringify({
+                subType: 'tool_complete',
+                subToolName: lastSubToolName,
+                subToolId: activeToolUseId,
+                ...(isFailure && { subToolIsError: true }),
+              }));
+              lastSubToolName = null;
+            }
             sessionId = message.session_id;
+            const resultMeta = {
+              subtype: message.subtype,
+              numTurns: message.num_turns,
+              durationMs: message.duration_ms,
+              costUsd: message.total_cost_usd,
+              stopReason: message.stop_reason,
+            };
+
             if (message.subtype === 'success') {
+              log.info(resultMeta, 'Claude Code session completed successfully');
               if (message.result && !resultText) {
                 resultText = message.result;
               }
             } else {
-              // Error result
+              // Error result — surface the subtype and details
               hasError = true;
               const errors = message.errors ?? [];
+              const denials = message.permission_denials ?? [];
+
+              log.error({ ...resultMeta, errors, permissionDenials: denials.length }, 'Claude Code session failed');
+
+              const parts: string[] = [];
+              parts.push(`[${message.subtype}] (${message.num_turns} turns, ${(message.duration_ms / 1000).toFixed(1)}s)`);
               if (errors.length > 0) {
-                resultText += `\n\nErrors: ${errors.join(', ')}`;
+                parts.push(`Errors: ${errors.join('; ')}`);
+              }
+              if (denials.length > 0) {
+                const denialSummary = denials.map(d => `${d.tool_name}`).join(', ');
+                parts.push(`Permission denied: ${denialSummary}`);
               }
+              resultText += `\n\n${parts.join('\n')}`;
             }
             break;
           }
           default:
-            // Ignore other message types (system, stream_event, etc.)
+            // Log unhandled message types at debug level for diagnostics
+            log.debug({ messageType: message.type }, 'Claude Code unhandled message type');
             break;
         }
       }
@@ -221,10 +401,26 @@ export const claudeCodeTool: Tool = {
         isError: hasError,
       };
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      log.error({ err }, 'Claude Code execution failed');
+      // Mark the last sub-tool as failed so the UI shows an error icon.
+      if (lastSubToolName) {
+        context.onOutput?.(JSON.stringify({
+          subType: 'tool_complete',
+          subToolName: lastSubToolName,
+          subToolIsError: true,
+        }));
+        lastSubToolName = null;
+      }
+
+      const errMessage = err instanceof Error ? err.message : String(err);
+      const recentStderr = stderrLines.slice(-20);
+      log.error({ err, stderrTail: recentStderr }, 'Claude Code execution failed');
+
+      const parts = [`Claude Code error: ${errMessage}`];
+      if (recentStderr.length > 0) {
+        parts.push(`\nSubprocess stderr (last ${recentStderr.length} lines):\n${recentStderr.join('\n')}`);
+      }
       return {
-        content: `Claude Code error: ${message}`,
+        content: parts.join(''),
         isError: true,
       };
     }

package/src/tools/contacts/contact-merge.ts

@@ -1,87 +1,55 @@
-import { RiskLevel } from '../../permissions/types.js';
-import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
-import type { ToolDefinition } from '../../providers/types.js';
-import { registerTool } from '../registry.js';
+import type { ToolContext, ToolExecutionResult } from '../types.js';
 import { mergeContacts, getContact } from '../../contacts/contact-store.js';
 
-const definition: ToolDefinition = {
-  name: 'contact_merge',
-  description: 'Merge two contacts when you discover they are the same person (e.g. same person on email and Slack). Combines channels, keeps the higher importance, and deletes the donor contact.',
-  input_schema: {
-    type: 'object',
-    properties: {
-      keep_id: {
-        type: 'string',
-        description: 'ID of the contact to keep (the surviving contact)',
-      },
-      merge_id: {
-        type: 'string',
-        description: 'ID of the contact to merge into the kept contact (will be deleted)',
-      },
-    },
-    required: ['keep_id', 'merge_id'],
-  },
-};
+export async function executeContactMerge(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const keepId = input.keep_id as string | undefined;
+  const mergeId = input.merge_id as string | undefined;
 
-class ContactMergeTool implements Tool {
-  name = 'contact_merge';
-  description = definition.description;
-  category = 'contacts';
-  defaultRiskLevel = RiskLevel.Medium;
-
-  getDefinition(): ToolDefinition {
-    return definition;
+  if (!keepId || typeof keepId !== 'string') {
+    return { content: 'Error: keep_id is required', isError: true };
+  }
+  if (!mergeId || typeof mergeId !== 'string') {
+    return { content: 'Error: merge_id is required', isError: true };
   }
 
-  async execute(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
-    const keepId = input.keep_id as string | undefined;
-    const mergeId = input.merge_id as string | undefined;
-
-    if (!keepId || typeof keepId !== 'string') {
-      return { content: 'Error: keep_id is required', isError: true };
-    }
-    if (!mergeId || typeof mergeId !== 'string') {
-      return { content: 'Error: merge_id is required', isError: true };
-    }
-
-    // Show what will be merged for clarity
-    const keepContact = getContact(keepId);
-    const mergeContact = getContact(mergeId);
-
-    if (!keepContact) {
-      return { content: `Error: Contact "${keepId}" not found`, isError: true };
-    }
-    if (!mergeContact) {
-      return { content: `Error: Contact "${mergeId}" not found`, isError: true };
-    }
-
-    try {
-      const merged = mergeContacts(keepId, mergeId);
+  // Show what will be merged for clarity
+  const keepContact = getContact(keepId);
+  const mergeContact = getContact(mergeId);
 
-      const channelList = merged.channels
-        .map((ch) => `  - ${ch.type}: ${ch.address}${ch.isPrimary ? ' (primary)' : ''}`)
-        .join('\n');
+  if (!keepContact) {
+    return { content: `Error: Contact "${keepId}" not found`, isError: true };
+  }
+  if (!mergeContact) {
+    return { content: `Error: Contact "${mergeId}" not found`, isError: true };
+  }
 
-      return {
-        content: [
-          `Merged "${mergeContact.displayName}" into "${keepContact.displayName}".`,
-          ``,
-          `Surviving contact (${merged.id}):`,
-          `  Name: ${merged.displayName}`,
-          `  Importance: ${merged.importance.toFixed(2)}`,
-          `  Interactions: ${merged.interactionCount}`,
-          merged.relationship ? `  Relationship: ${merged.relationship}` : null,
-          merged.channels.length > 0 ? `  Channels:\n${channelList}` : null,
-          ``,
-          `Deleted contact: ${mergeContact.displayName} (${mergeId})`,
-        ].filter(Boolean).join('\n'),
-        isError: false,
-      };
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      return { content: `Error: ${msg}`, isError: true };
-    }
+  try {
+    const merged = mergeContacts(keepId, mergeId);
+
+    const channelList = merged.channels
+      .map((ch) => `  - ${ch.type}: ${ch.address}${ch.isPrimary ? ' (primary)' : ''}`)
+      .join('\n');
+
+    return {
+      content: [
+        `Merged "${mergeContact.displayName}" into "${keepContact.displayName}".`,
+        ``,
+        `Surviving contact (${merged.id}):`,
+        `  Name: ${merged.displayName}`,
+        `  Importance: ${merged.importance.toFixed(2)}`,
+        `  Interactions: ${merged.interactionCount}`,
+        merged.relationship ? `  Relationship: ${merged.relationship}` : null,
+        merged.channels.length > 0 ? `  Channels:\n${channelList}` : null,
+        ``,
+        `Deleted contact: ${mergeContact.displayName} (${mergeId})`,
+      ].filter(Boolean).join('\n'),
+      isError: false,
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Error: ${msg}`, isError: true };
   }
 }
-
-registerTool(new ContactMergeTool());

package/src/tools/contacts/contact-search.ts

@@ -1,7 +1,4 @@
-import { RiskLevel } from '../../permissions/types.js';
-import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
-import type { ToolDefinition } from '../../providers/types.js';
-import { registerTool } from '../registry.js';
+import type { ToolContext, ToolExecutionResult } from '../types.js';
 import { searchContacts } from '../../contacts/contact-store.js';
 import type { ContactWithChannels } from '../../contacts/types.js';
 
@@ -18,85 +15,44 @@ function formatContactSummary(c: ContactWithChannels): string {
   return parts.join('\n');
 }
 
-const definition: ToolDefinition = {
-  name: 'contact_search',
-  description: 'Search for contacts by name, channel address, relationship type, or other criteria. Returns matching contacts with their channel information.',
-  input_schema: {
-    type: 'object',
-    properties: {
-      query: {
-        type: 'string',
-        description: 'Search by display name (partial match)',
-      },
-      channel_address: {
-        type: 'string',
-        description: 'Search by channel address (email, phone, handle — partial match)',
-      },
-      channel_type: {
-        type: 'string',
-        description: 'Filter by channel type when searching by address (email, slack, whatsapp, phone, etc.)',
-      },
-      relationship: {
-        type: 'string',
-        description: 'Filter by relationship type (exact match)',
-      },
-      limit: {
-        type: 'number',
-        description: 'Maximum results to return (default 20, max 100)',
-      },
-    },
-    required: [],
-  },
-};
-
-class ContactSearchTool implements Tool {
-  name = 'contact_search';
-  description = definition.description;
-  category = 'contacts';
-  defaultRiskLevel = RiskLevel.Low;
-
-  getDefinition(): ToolDefinition {
-    return definition;
+export async function executeContactSearch(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const query = input.query as string | undefined;
+  const channelAddress = input.channel_address as string | undefined;
+  const channelType = input.channel_type as string | undefined;
+  const relationship = input.relationship as string | undefined;
+  const limit = input.limit as number | undefined;
+
+  if (!query && !channelAddress && !relationship) {
+    return {
+      content: 'Error: At least one search criterion is required (query, channel_address, or relationship)',
+      isError: true,
+    };
   }
 
-  async execute(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
-    const query = input.query as string | undefined;
-    const channelAddress = input.channel_address as string | undefined;
-    const channelType = input.channel_type as string | undefined;
-    const relationship = input.relationship as string | undefined;
-    const limit = input.limit as number | undefined;
-
-    if (!query && !channelAddress && !relationship) {
-      return {
-        content: 'Error: At least one search criterion is required (query, channel_address, or relationship)',
-        isError: true,
-      };
+  try {
+    const results = searchContacts({
+      query,
+      channelAddress,
+      channelType,
+      relationship,
+      limit,
+    });
+
+    if (results.length === 0) {
+      return { content: 'No contacts found matching the search criteria.', isError: false };
     }
 
-    try {
-      const results = searchContacts({
-        query,
-        channelAddress,
-        channelType,
-        relationship,
-        limit,
-      });
-
-      if (results.length === 0) {
-        return { content: 'No contacts found matching the search criteria.', isError: false };
-      }
-
-      const lines = [`Found ${results.length} contact(s):\n`];
-      for (const contact of results) {
-        lines.push(formatContactSummary(contact));
-      }
-
-      return { content: lines.join('\n'), isError: false };
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      return { content: `Error: ${msg}`, isError: true };
+    const lines = [`Found ${results.length} contact(s):\n`];
+    for (const contact of results) {
+      lines.push(formatContactSummary(contact));
     }
+
+    return { content: lines.join('\n'), isError: false };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Error: ${msg}`, isError: true };
   }
 }
-
-registerTool(new ContactSearchTool());