vellum 0.2.1 → 0.2.2

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,11 @@ 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';
+
 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 +114,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 +160,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,12 +187,16 @@ 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) {
@@ -179,6 +212,12 @@ export const claudeCodeTool: Tool = {
       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) {
@@ -193,22 +232,43 @@ export const claudeCodeTool: Tool = {
           }
           case 'result': {
             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 +281,16 @@ export const claudeCodeTool: Tool = {
         isError: hasError,
       };
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      log.error({ err }, 'Claude Code execution failed');
+      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());

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

@@ -1,9 +1,5 @@
-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 { upsertContact } from '../../contacts/contact-store.js';
-import { CHANNEL_TYPES } from '../../contacts/types.js';
 
 function formatContact(c: ReturnType<typeof upsertContact>): string {
   const lines = [
@@ -25,113 +21,44 @@ function formatContact(c: ReturnType<typeof upsertContact>): string {
   return lines.join('\n');
 }
 
-const definition: ToolDefinition = {
-  name: 'contact_upsert',
-  description: 'Create or update a contact in the relationship graph. Use this to track people the user interacts with across channels (email, Slack, etc.).',
-  input_schema: {
-    type: 'object',
-    properties: {
-      id: {
-        type: 'string',
-        description: 'Contact ID to update. Omit to create a new contact (or auto-match by channel address).',
-      },
-      display_name: {
-        type: 'string',
-        description: 'Display name for the contact',
-      },
-      relationship: {
-        type: 'string',
-        description: 'Relationship type (e.g. colleague, friend, manager, client, family)',
-      },
-      importance: {
-        type: 'number',
-        description: 'Importance score 0-1 (default 0.5). Higher = more important.',
-      },
-      response_expectation: {
-        type: 'string',
-        description: 'Expected response speed (e.g. immediate, within_hours, within_day, casual)',
-      },
-      preferred_tone: {
-        type: 'string',
-        description: 'Preferred communication tone (e.g. formal, casual, friendly, professional)',
-      },
-      channels: {
-        type: 'array',
-        description: 'Communication channels for this contact',
-        items: {
-          type: 'object',
-          properties: {
-            type: {
-              type: 'string',
-              enum: [...CHANNEL_TYPES],
-              description: 'Channel type',
-            },
-            address: {
-              type: 'string',
-              description: 'Channel address (email address, Slack handle, phone number, etc.)',
-            },
-            is_primary: {
-              type: 'boolean',
-              description: 'Whether this is the primary channel for this type',
-            },
-          },
-          required: ['type', 'address'],
-        },
-      },
-    },
-    required: ['display_name'],
-  },
-};
-
-class ContactUpsertTool implements Tool {
-  name = 'contact_upsert';
-  description = definition.description;
-  category = 'contacts';
-  defaultRiskLevel = RiskLevel.Low;
-
-  getDefinition(): ToolDefinition {
-    return definition;
+export async function executeContactUpsert(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const displayName = input.display_name as string | undefined;
+  if (!displayName || typeof displayName !== 'string' || displayName.trim().length === 0) {
+    return { content: 'Error: display_name is required and must be a non-empty string', isError: true };
   }
 
-  async execute(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
-    const displayName = input.display_name as string | undefined;
-    if (!displayName || typeof displayName !== 'string' || displayName.trim().length === 0) {
-      return { content: 'Error: display_name is required and must be a non-empty string', isError: true };
-    }
-
-    const importance = input.importance as number | undefined;
-    if (importance !== undefined && (typeof importance !== 'number' || importance < 0 || importance > 1)) {
-      return { content: 'Error: importance must be a number between 0 and 1', isError: true };
-    }
+  const importance = input.importance as number | undefined;
+  if (importance !== undefined && (typeof importance !== 'number' || importance < 0 || importance > 1)) {
+    return { content: 'Error: importance must be a number between 0 and 1', isError: true };
+  }
 
-    const rawChannels = input.channels as Array<{ type: string; address: string; is_primary?: boolean }> | undefined;
-    const channels = rawChannels?.map((ch) => ({
-      type: ch.type,
-      address: ch.address,
-      isPrimary: ch.is_primary,
-    }));
+  const rawChannels = input.channels as Array<{ type: string; address: string; is_primary?: boolean }> | undefined;
+  const channels = rawChannels?.map((ch) => ({
+    type: ch.type,
+    address: ch.address,
+    isPrimary: ch.is_primary,
+  }));
 
-    try {
-      const contact = upsertContact({
-        id: input.id as string | undefined,
-        displayName: displayName.trim(),
-        relationship: input.relationship as string | undefined,
-        importance,
-        responseExpectation: input.response_expectation as string | undefined,
-        preferredTone: input.preferred_tone as string | undefined,
-        channels,
-      });
+  try {
+    const contact = upsertContact({
+      id: input.id as string | undefined,
+      displayName: displayName.trim(),
+      relationship: input.relationship as string | undefined,
+      importance,
+      responseExpectation: input.response_expectation as string | undefined,
+      preferredTone: input.preferred_tone as string | undefined,
+      channels,
+    });
 
-      const isNew = contact.createdAt === contact.updatedAt;
-      return {
-        content: `${isNew ? 'Created' : 'Updated'} contact:\n${formatContact(contact)}`,
-        isError: false,
-      };
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      return { content: `Error: ${msg}`, isError: true };
-    }
+    return {
+      content: `${contact.created ? 'Created' : 'Updated'} contact:\n${formatContact(contact)}`,
+      isError: false,
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Error: ${msg}`, isError: true };
   }
 }
-
-registerTool(new ContactUpsertTool());

package/src/tools/credentials/vault.ts

@@ -95,15 +95,19 @@ function findStoredOAuthField(service: string, fieldNames: string[]): string | u
     }
   }
 
-  // Fallback: check credential metadata on the access_token record, where
-  // oauth2_connect persists the client config after a successful flow.
+  // Legacy fallback: check credential metadata on the access_token record.
+  // Older OAuth2 flows stored client_id/client_secret only in metadata JSON.
+  // New flows persist them in the keychain (checked above) for defense in depth.
   const metadataKey = fieldNames.some((f) => f.includes('client_id'))
     ? 'oauth2ClientId' as const
     : 'oauth2ClientSecret' as const;
   for (const svc of servicesToCheck) {
     const meta = getCredentialMetadata(svc, 'access_token');
     const value = meta?.[metadataKey];
-    if (value) return value;
+    if (value) {
+      log.debug({ service: svc, field: metadataKey }, 'OAuth client credential resolved from metadata (legacy fallback)');
+      return value;
+    }
   }
 
   return undefined;
@@ -569,7 +573,7 @@ class CredentialStoreTool implements Tool {
             return { content: 'Error: failed to store access token in secure storage', isError: true };
           }
 
-          const expiresAt = tokens.expiresIn ? Date.now() + tokens.expiresIn * 1000 : undefined;
+          const expiresAt = tokens.expiresIn ? Date.now() + tokens.expiresIn * 1000 : null;
 
           let accountInfo: string | undefined;
           if (userinfoUrl && grantedScopes.some((s) => s.includes('userinfo'))) {
@@ -586,6 +590,18 @@ class CredentialStoreTool implements Tool {
             }
           }
 
+          // Persist client credentials in keychain for defense in depth
+          const clientIdStored = setSecureKey(`credential:${service}:client_id`, clientId);
+          if (!clientIdStored) {
+            return { content: 'Error: failed to store client_id in secure storage', isError: true };
+          }
+          if (clientSecret) {
+            const clientSecretStored = setSecureKey(`credential:${service}:client_secret`, clientSecret);
+            if (!clientSecretStored) {
+              return { content: 'Error: failed to store client_secret in secure storage', isError: true };
+            }
+          }
+
           upsertCredentialMetadata(service, 'access_token', {
             allowedTools: allowedTools ?? [],
             expiresAt,