vellum 0.2.1 → 0.2.2

package/src/subagent/manager.ts

@@ -52,10 +52,18 @@ interface ManagedSubagent {
   parentSendToClient: (msg: ServerMessage) => void;
 }
 
+export interface SubagentNotificationInfo {
+  subagentId: string;
+  label: string;
+  status: 'completed' | 'failed' | 'aborted';
+  error?: string;
+}
+
 export type ParentNotifyCallback = (
   parentSessionId: string,
   message: string,
   sendToClient: (msg: ServerMessage) => void,
+  notification: SubagentNotificationInfo,
 ) => void;
 
 export class SubagentManager {
@@ -221,6 +229,8 @@ export class SubagentManager {
       await managed.session.runAgentLoop(objective, messageId, onEvent);
 
       // Agent loop completed successfully.
+      // Copy usage stats from the session before sending status (which includes usage).
+      managed.state.usage = { ...managed.session.usageStats };
       // Only update state + notify if still non-terminal (guards against abort race).
       if (!TERMINAL_STATUSES.has(managed.state.status)) {
         managed.state.completedAt = Date.now();
@@ -235,6 +245,7 @@ export class SubagentManager {
       const errorMsg = err instanceof Error ? err.message : String(err);
       managed.state.error = errorMsg;
       managed.state.completedAt = Date.now();
+      managed.state.usage = { ...managed.session.usageStats };
 
       // Only update status if not already terminal (e.g. aborted).
       if (!TERMINAL_STATUSES.has(managed.state.status)) {
@@ -267,16 +278,28 @@ export class SubagentManager {
     managed.session.abort();
     managed.state.completedAt = Date.now();
     if (parentSendToClient) {
-      this.setStatus(subagentId, 'aborted', parentSendToClient);
-      // Notify parent about the abort — skip when the parent already has the
-      // tool result (e.g. subagent_abort tool) to avoid duplicate turns.
+      // Route the status update through the stored parent sender so the
+      // owning session's UI chip updates, even when the abort comes from a
+      // different socket (e.g. after thread switching). Fall back to the
+      // caller-provided sender if no stored sender exists.
+      const statusSender = managed.parentSendToClient ?? parentSendToClient;
+      this.setStatus(subagentId, 'aborted', statusSender);
+      // Notify parent that the subagent was explicitly aborted — tell it NOT to re-spawn.
+      // Skip when the parent LLM itself called subagent_abort (it already has the tool result).
       if (this.onSubagentFinished && !options?.suppressNotification) {
         const label = managed.state.config.label;
+        const message =
+          `[Subagent "${label}" was explicitly aborted]\n\n` +
+          `This subagent was cancelled on purpose. Do NOT re-spawn or retry it.`;
         try {
+          // Use the managed subagent's stored parentSendToClient so the
+          // notification routes to the parent session's socket, not the
+          // aborting socket (which may be a different thread after switching).
           this.onSubagentFinished(
             managed.state.config.parentSessionId,
-            `[Subagent "${label}" was aborted]`,
-            parentSendToClient,
+            message,
+            managed.parentSendToClient,
+            { subagentId, label, status: 'aborted' },
           );
         } catch (err) {
           log.error({ subagentId, err }, 'Failed to notify parent about abort');
@@ -460,16 +483,25 @@ export class SubagentManager {
     if (outcome === 'completed') {
       message =
         `[Subagent "${config.label}" completed]\n\n` +
-        `Use subagent_read with subagent_id "${config.id}" to retrieve the full output.`;
+        `Use subagent_read with subagent_id "${config.id}" to retrieve the full output.\n` +
+        `Do NOT re-spawn this subagent — just read and share the results.`;
     } else {
       const error = managed.state.error ?? 'Unknown error';
       message =
         `[Subagent "${config.label}" failed]\n\n` +
-        `Error: ${error}`;
+        `Error: ${error}\n` +
+        `Do NOT re-spawn or retry this subagent unless the user explicitly asks.`;
     }
 
+    const notification: SubagentNotificationInfo = {
+      subagentId: config.id,
+      label: config.label,
+      status: outcome,
+      ...(outcome === 'failed' ? { error: managed.state.error ?? 'Unknown error' } : {}),
+    };
+
     try {
-      this.onSubagentFinished(config.parentSessionId, message, parentSendToClient);
+      this.onSubagentFinished(config.parentSessionId, message, parentSendToClient, notification);
     } catch (err) {
       log.error({ subagentId: config.id, err }, 'Failed to notify parent session');
     }

package/src/swarm/backend-claude-code.ts

@@ -12,6 +12,9 @@ import { getProfilePolicy } from './worker-backend.js';
 
 const log = getLogger('swarm-backend-claude-code');
 
+const MAX_CLAUDE_CODE_DEPTH = 1;
+const DEPTH_ENV_VAR = 'VELLUM_CLAUDE_CODE_DEPTH';
+
 /**
  * Create a Claude Code worker backend that enforces profile-based tool policies.
  * Uses the Claude Agent SDK to run autonomous worker tasks.
@@ -28,6 +31,7 @@ export function createClaudeCodeBackend(): SwarmWorkerBackend {
 
     async runTask(input: SwarmWorkerBackendInput) {
       const start = Date.now();
+      const stderrLines: string[] = [];
       try {
         const { query } = await import('@anthropic-ai/claude-agent-sdk');
         const config = getConfig();
@@ -49,6 +53,22 @@ export function createClaudeCodeBackend(): SwarmWorkerBackend {
           return { behavior: 'allow' as const };
         };
 
+        // Enforce nesting depth limit
+        const currentDepth = parseInt(process.env[DEPTH_ENV_VAR] ?? '0', 10);
+        if (currentDepth >= MAX_CLAUDE_CODE_DEPTH) {
+          log.warn({ currentDepth, max: MAX_CLAUDE_CODE_DEPTH }, 'Swarm worker nesting depth exceeded');
+          return { success: false, output: `Nesting depth exceeded (depth ${currentDepth}, max ${MAX_CLAUDE_CODE_DEPTH})`, failureReason: 'backend_unavailable' as const, durationMs: Date.now() - start };
+        }
+
+        // Strip the SDK's nesting guard but set our own depth counter.
+        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;
+
         const conversation = query({
           prompt: input.prompt,
           options: {
@@ -57,20 +77,48 @@ export function createClaudeCodeBackend(): SwarmWorkerBackend {
             canUseTool,
             permissionMode: 'default',
             maxTurns: 30,
-            env: { ...process.env, ANTHROPIC_API_KEY: apiKey },
+            env: subprocessEnv,
+            stderr: (data: string) => {
+              const trimmed = data.trimEnd();
+              if (trimmed) {
+                stderrLines.push(trimmed);
+                log.debug({ stderr: trimmed }, 'Swarm worker subprocess stderr');
+              }
+            },
           },
         });
 
         let resultText = '';
+        let hasError = false;
         for await (const message of conversation) {
           if (input.signal?.aborted) break;
-          if (message.type === 'assistant' && message.message?.content) {
-            for (const block of message.message.content) {
-              if (block.type === 'text') resultText += block.text;
+          if (message.type === 'assistant') {
+            if (message.error) {
+              log.error({ error: message.error, sessionId: message.session_id }, 'Swarm worker assistant message error');
+              hasError = true;
+              resultText += `\n[Claude Code error: ${message.error}]`;
+            }
+            if (message.message?.content) {
+              for (const block of message.message.content) {
+                if (block.type === 'text') resultText += block.text;
+              }
             }
           } else if (message.type === 'result') {
-            if (message.subtype === 'success' && message.result && !resultText) {
-              resultText = message.result;
+            if (message.subtype === 'success') {
+              log.info({ numTurns: message.num_turns, durationMs: message.duration_ms, costUsd: message.total_cost_usd }, 'Swarm worker completed');
+              if (message.result && !resultText) {
+                resultText = message.result;
+              }
+            } else {
+              hasError = true;
+              const errors = message.errors ?? [];
+              const denials = message.permission_denials ?? [];
+              log.error({ subtype: message.subtype, errors, permissionDenials: denials.length, numTurns: message.num_turns, durationMs: message.duration_ms }, 'Swarm worker session failed');
+
+              const parts: string[] = [`[${message.subtype}] (${message.num_turns} turns, ${(message.duration_ms / 1000).toFixed(1)}s)`];
+              if (errors.length > 0) parts.push(`Errors: ${errors.join('; ')}`);
+              if (denials.length > 0) parts.push(`Permission denied: ${denials.map(d => d.tool_name).join(', ')}`);
+              resultText += `\n${parts.join('\n')}`;
             }
           }
         }
@@ -80,10 +128,17 @@ export function createClaudeCodeBackend(): SwarmWorkerBackend {
           return { success: false, output: 'Cancelled (aborted)', failureReason: 'cancelled' as const, durationMs: Date.now() - start };
         }
 
-        return { success: true, output: resultText || 'Completed', durationMs: Date.now() - start };
+        return { success: !hasError, output: resultText || 'Completed', durationMs: Date.now() - start };
       } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return { success: false, output: message, failureReason: 'backend_unavailable' as const, durationMs: Date.now() - start };
+        const errMessage = err instanceof Error ? err.message : String(err);
+        const recentStderr = stderrLines.slice(-20);
+        log.error({ err, stderrTail: recentStderr }, 'Swarm worker execution failed');
+
+        const parts = [errMessage];
+        if (recentStderr.length > 0) {
+          parts.push(`\nSubprocess stderr (last ${recentStderr.length} lines):\n${recentStderr.join('\n')}`);
+        }
+        return { success: false, output: parts.join(''), failureReason: 'backend_unavailable' as const, durationMs: Date.now() - start };
       }
     },
   };

package/src/swarm/worker-prompts.ts

@@ -1,4 +1,5 @@
 import type { SwarmRole, SwarmTaskResult } from './types.js';
+import { truncate } from '../util/truncate.js';
 
 /**
  * Build a role-specific worker prompt for a swarm task.
@@ -70,7 +71,7 @@ export function parseWorkerOutput(raw: string): Pick<SwarmTaskResult, 'summary'
   }
 
   return {
-    summary: raw.slice(0, 500),
+    summary: truncate(raw, 500, ''),
     artifacts: [],
     issues: [],
     nextSteps: [],

package/src/tasks/SPEC.md

@@ -87,18 +87,23 @@ Each task run creates a new conversation thread with `threadType: 'background'`.
 
 ### Lifecycle
 
-1. **Start**: The daemon creates a `background` thread, substitutes template
-   placeholders, and sends the prompt to the LLM. An IPC notification
-   (`task_run_started`) is broadcast to all connected clients with the run ID,
-   task ID, and thread ID.
-2. **Completion**: When the LLM response is received and stored, the daemon
-   broadcasts a `task_run_completed` notification with the run ID, task ID,
-   thread ID, and a status (`success` | `error`).
-3. **Visibility**: Background threads are excluded from the default thread list
-   (existing behavior in `conversation-store.ts`). Clients can query for them
-   explicitly to surface task results in a dedicated UI.
-
-**Why background threads:** Reuses the existing `threadType: 'background'`
+1. **Preflight**: The client requests a permission preflight for the work item.
+   The daemon classifies risk for each required tool and returns the permission
+   set. The client displays an approval dialog; approved tools are stored on
+   the work item.
+2. **Start**: The daemon creates a `background` conversation, substitutes
+   template placeholders, sets up ephemeral permission rules for the approved
+   tools, and processes the rendered prompt through a daemon `Session`. Status
+   updates are broadcast to all connected clients via `work_item_status_changed`
+   and `tasks_changed` IPC messages.
+3. **Completion**: When the session finishes, the work item transitions to
+   `awaiting_review` (on success) or `failed` (on error). The daemon broadcasts
+   the final status to all clients.
+4. **Visibility**: Background conversations are excluded from the default thread
+   list (existing behavior in `conversation-store.ts`). Clients can query for
+   them explicitly to surface task results in a dedicated UI.
+
+**Why background conversations:** Reuses the existing `threadType: 'background'`
 infrastructure. Task runs don't interrupt the user's current conversation, and
 clients can choose how and when to display results (toast, panel, separate
 tab).
@@ -107,27 +112,28 @@ tab).
 
 ## 4. Safety Invariants
 
-- **No auto-execution**: Tasks are never triggered automatically. Every run
-  requires an explicit user action (CLI command, API call, or UI button press).
+- **Explicit trigger required**: Task runs are triggered either by an explicit
+  user action (UI button press, API call) or by a user-configured schedule
+  (`run_task:<task_id>` via the scheduler).
 - **Ephemeral permission bundles**: If a task is configured with tool access,
   the permission grants are scoped to the single run and discarded afterward.
   No persistent allowlist entries are created on behalf of a task.
-- **High-risk tools always prompt**: Regardless of any task-level permission
-  configuration, tools classified as `RiskLevel.High` (destructive shell
-  commands, private-network fetches, etc.) always require interactive user
-  confirmation. This invariant cannot be overridden by task definitions.
+- **High-risk tools require upfront approval**: Tools classified as
+  `RiskLevel.High` (destructive shell commands, private-network fetches, etc.)
+  are surfaced in the preflight dialog so the user can explicitly approve or
+  deny them before execution begins. During the run itself, approved tools
+  (including high-risk ones) execute without further prompting.
 
 ---
 
-## 5. PR Dependency Chain
+## 5. Implementation Notes
 
-Implementation is split into sequential PRs, each building on the previous:
+The implementation is complete. Key modules:
 
-| PR | Title | What it delivers |
-|----|-------|------------------|
-| 0  | Spec decisions | This document. |
-| 1  | Schema + storage | `tasks` and `task_runs` tables, Drizzle schema, migration in `db.ts`, CRUD functions in `task-store.ts`. |
-| 2  | Template engine | `renderTemplate()` — placeholder substitution with input validation against the JSON Schema. |
-| 3  | Run executor | `executeTaskRun()` — creates background thread, calls LLM, writes result, broadcasts IPC notifications (`task_run_started`, `task_run_completed`). |
-| 4  | CLI surface | `vellum task create`, `vellum task run`, `vellum task list` commands. |
-| 5  | IPC + macOS integration | Wire up IPC message types; macOS client displays task run results. |
+| Module | What it delivers |
+|--------|------------------|
+| `task-store.ts` | `tasks` and `task_runs` tables, CRUD functions. |
+| `task-runner.ts` | `runTask()` — creates background conversation, renders template, processes through daemon Session. |
+| `ephemeral-permissions.ts` | Scoped permission rules for the duration of a single task run. |
+| `work-items.ts` (daemon handler) | IPC handlers for preflight, run, cancel, and status queries. |
+| Bundled skill (`tasks/`) | Tool definitions (`task_save`, `task_run`, `task_list`, `task_delete`, `task_list_*`) for the LLM. |

package/src/tasks/ephemeral-permissions.ts

@@ -21,19 +21,28 @@ export function clearTaskRunRules(taskRunId: string): void {
 /**
  * Build ephemeral TrustRule entries from a task's required_tools list.
  *
- * Each rule allows the specified tool with a wildcard pattern scoped to the
- * given working directory. Priority is set to 50 — lower than user rules (100)
- * so that user deny rules still take precedence. `allowHighRisk` is NOT set,
- * so high-risk operations continue to prompt for approval.
+ * Each rule allows the specified tool with a wildcard pattern scoped
+ * globally ('everywhere'). The scope is intentionally broad because the
+ * session's workingDir (sandbox path like ~/.vellum/workspace) differs
+ * from process.cwd() — using a directory-scoped rule would fail
+ * matchesScope() and silently miss. Priority is set to 75 — above
+ * default rules (50) so pre-approved tools aren't shadowed by default
+ * `ask` rules (which would trigger prompting and auto-deny in
+ * non-interactive task runs), but below user rules (100) so user deny
+ * rules still take precedence. `allowHighRisk` is set because task runs
+ * execute asynchronously without interactive confirmation — the client
+ * pre-approves tools via the preflight flow before execution begins,
+ * so there is no interactive prompt during the run itself.
  */
-export function buildTaskRules(taskRunId: string, requiredTools: string[], workingDir: string): TrustRule[] {
+export function buildTaskRules(taskRunId: string, requiredTools: string[], _workingDir: string): TrustRule[] {
   return requiredTools.map((tool) => ({
     id: `ephemeral:${taskRunId}:${tool}`,
     tool,
     pattern: '**',
-    scope: workingDir,
+    scope: 'everywhere',
     decision: 'allow' as const,
-    priority: 50,
+    allowHighRisk: true,
+    priority: 75,
     createdAt: Date.now(),
     principalKind: 'task',
     principalId: taskRunId,

package/src/tasks/task-compiler.ts

@@ -3,6 +3,8 @@ import { getDb } from '../memory/db.js';
 import { messages as messagesTable } from '../memory/schema.js';
 import { createTask } from './task-store.js';
 import type { Task } from './task-store.js';
+import { truncate } from '../util/truncate.js';
+import { sanitizeToolList } from './tool-sanitizer.js';
 
 /** Output schema for the task compiler. */
 export interface CompiledTask {
@@ -44,8 +46,8 @@ export function compileTaskFromConversation(conversationId: string): CompiledTas
   // Extract user message text content
   const userText = extractTextContent(firstUserMsg.content);
 
-  // Extract unique tool names from assistant messages
-  const requiredTools = extractToolNames(msgs);
+  // Extract unique tool names from assistant messages.
+  const requiredTools = sanitizeToolList(extractToolNames(msgs));
 
   // Build template with placeholder substitutions
   const { template, properties } = buildTemplate(userText);
@@ -193,6 +195,5 @@ function buildTemplate(text: string): {
 function deriveTitle(text: string): string {
   // Take the first line and trim whitespace
   const firstLine = text.split('\n')[0].trim();
-  if (firstLine.length <= 60) return firstLine;
-  return firstLine.slice(0, 57) + '...';
+  return truncate(firstLine, 60);
 }

package/src/tasks/task-runner.ts

@@ -2,6 +2,7 @@ import { getLogger } from '../util/logger.js';
 import { createConversation } from '../memory/conversation-store.js';
 import { getTask, createTaskRun, updateTaskRun } from './task-store.js';
 import { buildTaskRules, setTaskRunRules, clearTaskRunRules } from './ephemeral-permissions.js';
+import { sanitizeToolList } from './tool-sanitizer.js';
 
 const log = getLogger('task-runner');
 
@@ -9,6 +10,8 @@ export interface TaskRunOptions {
   taskId: string;
   inputs?: Record<string, string>;
   workingDir: string;
+  /** Pre-approved tools from the permission preflight flow. When set, only these tools get ephemeral allow rules. */
+  approvedTools?: string[];
 }
 
 export interface TaskRunResult {
@@ -32,7 +35,7 @@ export function renderTemplate(template: string, inputs: Record<string, string>)
  */
 export async function runTask(
   opts: TaskRunOptions,
-  processMessage: (conversationId: string, message: string) => Promise<void>,
+  processMessage: (conversationId: string, message: string, taskRunId: string) => Promise<void>,
 ): Promise<TaskRunResult> {
   const task = getTask(opts.taskId);
   if (!task) {
@@ -47,9 +50,11 @@ export async function runTask(
     memoryScopeId: `task:${task.id}`,
   });
 
-  // Build and register ephemeral permission rules from the task's required tools
-  const requiredTools: string[] = task.requiredTools ? JSON.parse(task.requiredTools) : [];
-  const rules = buildTaskRules(run.id, requiredTools, opts.workingDir);
+  // Build and register ephemeral permission rules. If the user pre-approved
+  // specific tools via the preflight flow, use those instead of all requiredTools.
+  const requiredTools = sanitizeToolList(task.requiredTools ? JSON.parse(task.requiredTools) : []);
+  const toolsForRules = opts.approvedTools ? sanitizeToolList(opts.approvedTools) : requiredTools;
+  const rules = buildTaskRules(run.id, toolsForRules, opts.workingDir);
   setTaskRunRules(run.id, rules);
 
   try {
@@ -58,7 +63,7 @@ export async function runTask(
     updateTaskRun(run.id, { status: 'running', startedAt: Date.now() });
 
     log.info({ taskId: task.id, taskRunId: run.id, conversationId: conversation.id }, 'Executing task');
-    await processMessage(conversation.id, renderedTemplate);
+    await processMessage(conversation.id, renderedTemplate, run.id);
 
     updateTaskRun(run.id, { status: 'completed', finishedAt: Date.now() });
 

package/src/tasks/task-scheduler.ts

@@ -1,7 +1,7 @@
 import { createSchedule } from '../schedule/schedule-store.js';
 
 /**
- * Create a schedule that runs a task on a cron expression.
+ * Create a recurrence schedule that runs a task on a cron or RRULE expression.
  * The scheduler detects the `run_task:<taskId>` message format
  * and delegates to runTask() instead of processMessage().
  */

package/src/tasks/tool-sanitizer.ts

@@ -0,0 +1,36 @@
+import { getTool, getAllTools } from '../tools/registry.js';
+
+/**
+ * Deduplicate and sort a list of tool names, validating against the live
+ * tool registry. Unknown tool names are logged at warn level but kept —
+ * they may refer to skill tools that will be loaded at runtime.
+ *
+ * The returned array is deterministic: sorted alphabetically with no duplicates.
+ */
+export function sanitizeToolList(tools: string[]): string[] {
+  const seen = new Set<string>();
+
+  for (const tool of tools) {
+    if (!tool || typeof tool !== 'string') continue;
+    seen.add(tool);
+  }
+
+  return [...seen].sort();
+}
+
+/**
+ * Get all registered tool names from the live tool registry.
+ * Used as the fallback when a task/work-item has no explicit requiredTools.
+ */
+export function getRegisteredToolNames(): string[] {
+  return getAllTools()
+    .filter((t) => t.executionMode !== 'proxy' && t.origin !== 'skill')
+    .map((t) => t.name)
+    .sort();
+}
+
+/** Look up the human-readable description for a tool from the registry. */
+export function getToolDescription(tool: string): string {
+  const registered = getTool(tool);
+  return registered?.description ?? tool;
+}

package/src/tools/assets/search.ts

@@ -214,7 +214,7 @@ export function searchAttachments(params: AssetSearchParams): StoredAttachment[]
 
     const limit = Math.min(params.limit ?? DEFAULT_LIMIT, MAX_RESULTS);
     const stmt = raw.prepare(
-      `SELECT a.id, a.assistant_id, a.original_filename, a.mime_type, a.size_bytes, a.kind, a.created_at
+      `SELECT a.id, a.original_filename, a.mime_type, a.size_bytes, a.kind, a.thumbnail_base64, a.created_at
        FROM attachments a
        WHERE ${whereParts.join(' AND ')}
        ORDER BY a.created_at DESC
@@ -223,21 +223,21 @@ export function searchAttachments(params: AssetSearchParams): StoredAttachment[]
 
     const rows = stmt.all(...bindValues, limit) as Array<{
       id: string;
-      assistant_id: string;
       original_filename: string;
       mime_type: string;
       size_bytes: number;
       kind: string;
+      thumbnail_base64: string | null;
       created_at: number;
     }>;
 
     return rows.map((r) => ({
       id: r.id,
-      assistantId: r.assistant_id,
       originalFilename: r.original_filename,
       mimeType: r.mime_type,
       sizeBytes: r.size_bytes,
       kind: r.kind,
+      thumbnailBase64: r.thumbnail_base64,
       createdAt: r.created_at,
     }));
   }
@@ -249,11 +249,11 @@ export function searchAttachments(params: AssetSearchParams): StoredAttachment[]
   const query = db
     .select({
       id: attachments.id,
-      assistantId: attachments.assistantId,
       originalFilename: attachments.originalFilename,
       mimeType: attachments.mimeType,
       sizeBytes: attachments.sizeBytes,
       kind: attachments.kind,
+      thumbnailBase64: attachments.thumbnailBase64,
       createdAt: attachments.createdAt,
     })
     .from(attachments)