@vellumai/assistant 0.3.2 → 0.3.3

package/src/runtime/routes/channel-routes.ts

@@ -53,27 +53,34 @@ const log = getLogger('runtime-http');
 
 /**
  * Header name used by the gateway to prove a request originated from it.
- * The gateway sets this to the shared bearer token; the runtime validates
- * it using constant-time comparison. Requests to `/channels/inbound`
- * that lack a valid gateway-origin proof are rejected with 403.
+ * The gateway sends a dedicated gateway-origin secret (or the bearer token
+ * as fallback). The runtime validates it using constant-time comparison.
+ * Requests to `/channels/inbound` that lack a valid proof are rejected with 403.
  */
 export const GATEWAY_ORIGIN_HEADER = 'X-Gateway-Origin';
 
 /**
  * Validate that the request carries a valid gateway-origin proof.
- * Returns true when the header value matches the expected bearer token
- * using constant-time comparison to prevent timing attacks.
+ * Uses constant-time comparison to prevent timing attacks.
  *
- * When no bearer token is configured (e.g., local dev without auth),
- * gateway-origin validation is skipped — the server is already
- * unauthenticated, so there is no shared secret to verify against.
+ * The `gatewayOriginSecret` parameter is the dedicated secret configured
+ * via `RUNTIME_GATEWAY_ORIGIN_SECRET`. When set, only this value is
+ * accepted. When not set, the function falls back to `bearerToken` for
+ * backward compatibility. When neither is configured (local dev), validation
+ * is skipped entirely.
  */
-export function verifyGatewayOrigin(req: Request, bearerToken?: string): boolean {
-  if (!bearerToken) return true; // No shared secret configured — skip validation
+export function verifyGatewayOrigin(
+  req: Request,
+  bearerToken?: string,
+  gatewayOriginSecret?: string,
+): boolean {
+  // Determine the expected secret: prefer dedicated secret, fall back to bearer token
+  const expectedSecret = gatewayOriginSecret ?? bearerToken;
+  if (!expectedSecret) return true; // No shared secret configured — skip validation
   const provided = req.headers.get(GATEWAY_ORIGIN_HEADER);
   if (!provided) return false;
   const a = Buffer.from(provided);
-  const b = Buffer.from(bearerToken);
+  const b = Buffer.from(expectedSecret);
   if (a.length !== b.length) return false;
   return timingSafeEqual(a, b);
 }
@@ -84,6 +91,9 @@ export function verifyGatewayOrigin(req: Request, bearerToken?: string): boolean
 
 export type ActorRole = 'guardian' | 'non-guardian' | 'unverified_channel';
 
+/** Sub-reason for `unverified_channel` denials. */
+export type DenialReason = 'no_binding' | 'no_identity';
+
 export interface GuardianContext {
   actorRole: ActorRole;
   /** The guardian's delivery chat ID (from the guardian binding). */
@@ -96,6 +106,8 @@ export interface GuardianContext {
   requesterExternalUserId?: string;
   /** The requester's chat ID. */
   requesterChatId?: string;
+  /** Sub-reason when actorRole is 'unverified_channel'. */
+  denialReason?: DenialReason;
 }
 
 /** Guardian approval request expiry (30 minutes). */
@@ -142,7 +154,7 @@ function parseCallbackData(data: string): ApprovalDecisionResult | null {
   return { action: action as ApprovalAction, source: 'telegram_button', runId };
 }
 
-export async function handleDeleteConversation(req: Request): Promise<Response> {
+export async function handleDeleteConversation(req: Request, assistantId: string = 'self'): Promise<Response> {
   const body = await req.json() as {
     sourceChannel?: string;
     externalChatId?: string;
@@ -157,8 +169,12 @@ export async function handleDeleteConversation(req: Request): Promise<Response>
     return Response.json({ error: 'externalChatId is required' }, { status: 400 });
   }
 
-  const conversationKey = `${sourceChannel}:${externalChatId}`;
-  deleteConversationKey(conversationKey);
+  // Delete both legacy and scoped conversation key aliases to handle
+  // migration scenarios where either or both keys may exist.
+  const legacyKey = `${sourceChannel}:${externalChatId}`;
+  const scopedKey = `asst:${assistantId}:${sourceChannel}:${externalChatId}`;
+  deleteConversationKey(legacyKey);
+  deleteConversationKey(scopedKey);
   externalConversationStore.deleteBindingByChannelChat(sourceChannel, externalChatId);
 
   return Response.json({ ok: true });
@@ -169,11 +185,13 @@ export async function handleChannelInbound(
   processMessage?: MessageProcessor,
   bearerToken?: string,
   runOrchestrator?: RunOrchestrator,
+  assistantId: string = 'self',
+  gatewayOriginSecret?: string,
 ): Promise<Response> {
   // Reject requests that lack valid gateway-origin proof. This ensures
   // channel inbound messages can only arrive via the gateway (which
   // performs webhook-level verification) and not via direct HTTP calls.
-  if (!verifyGatewayOrigin(req, bearerToken)) {
+  if (!verifyGatewayOrigin(req, bearerToken, gatewayOriginSecret)) {
     log.warn('Rejected channel inbound request: missing or invalid gateway-origin proof');
     return Response.json(
       { error: 'Forbidden: missing gateway-origin proof', code: 'GATEWAY_ORIGIN_REQUIRED' },
@@ -258,7 +276,7 @@ export async function handleChannelInbound(
       sourceChannel,
       externalChatId,
       externalMessageId,
-      { sourceMessageId },
+      { sourceMessageId, assistantId },
     );
 
     if (editResult.duplicate) {
@@ -285,7 +303,7 @@ export async function handleChannelInbound(
       if (original) break;
       if (attempt < EDIT_LOOKUP_RETRIES) {
         log.info(
-          { assistantId: "self", sourceMessageId, attempt: attempt + 1, maxAttempts: EDIT_LOOKUP_RETRIES },
+          { assistantId, sourceMessageId, attempt: attempt + 1, maxAttempts: EDIT_LOOKUP_RETRIES },
           'Original message not linked yet, retrying edit lookup',
         );
         await new Promise((resolve) => setTimeout(resolve, EDIT_LOOKUP_DELAY_MS));
@@ -295,12 +313,12 @@ export async function handleChannelInbound(
     if (original) {
       conversationStore.updateMessageContent(original.messageId, content ?? '');
       log.info(
-        { assistantId: "self", sourceMessageId, messageId: original.messageId },
+        { assistantId, sourceMessageId, messageId: original.messageId },
         'Updated message content from edited_message',
       );
     } else {
       log.warn(
-        { assistantId: "self", sourceChannel, externalChatId, sourceMessageId },
+        { assistantId, sourceChannel, externalChatId, sourceMessageId },
         'Could not find original message for edit after retries, ignoring',
       );
     }
@@ -317,7 +335,7 @@ export async function handleChannelInbound(
     sourceChannel,
     externalChatId,
     externalMessageId,
-    { sourceMessageId },
+    { sourceMessageId, assistantId },
   );
 
   // Upsert external conversation binding with sender metadata
@@ -351,7 +369,7 @@ export async function handleChannelInbound(
     const token = trimmedContent.slice('/guardian_verify '.length).trim();
     if (token.length > 0) {
       const verifyResult = validateAndConsumeChallenge(
-        'self',
+        assistantId,
         sourceChannel,
         token,
         body.senderExternalUserId,
@@ -384,11 +402,15 @@ export async function handleChannelInbound(
   // Determine whether the sender is the guardian for this channel.
   // When a guardian binding exists, non-guardian actors get stricter
   // side-effect controls and their approvals route to the guardian's chat.
+  //
+  // Guardian enforcement runs independently of CHANNEL_APPROVALS_ENABLED.
+  // The approval flag only gates the interactive approval prompting UX;
+  // actor-role resolution and fail-closed denial are always active.
   let guardianCtx: GuardianContext = { actorRole: 'guardian' };
-  if (isChannelApprovalsEnabled() && body.senderExternalUserId) {
-    const senderIsGuardian = isGuardian('self', sourceChannel, body.senderExternalUserId);
+  if (body.senderExternalUserId) {
+    const senderIsGuardian = isGuardian(assistantId, sourceChannel, body.senderExternalUserId);
     if (!senderIsGuardian) {
-      const binding = getGuardianBinding('self', sourceChannel);
+      const binding = getGuardianBinding(assistantId, sourceChannel);
       if (binding) {
         const requesterLabel = body.senderUsername
           ? `@${body.senderUsername}`
@@ -406,11 +428,25 @@ export async function handleChannelInbound(
         // unverified. Sensitive actions will be auto-denied (fail-closed).
         guardianCtx = {
           actorRole: 'unverified_channel',
+          denialReason: 'no_binding',
           requesterExternalUserId: body.senderExternalUserId,
           requesterChatId: externalChatId,
         };
       }
     }
+  } else {
+    // No sender identity available — fail-closed when guardian enforcement
+    // is active for this channel. If a binding exists, unknown actors must
+    // not be granted default guardian permissions.
+    const binding = getGuardianBinding(assistantId, sourceChannel);
+    if (binding) {
+      guardianCtx = {
+        actorRole: 'unverified_channel',
+        denialReason: 'no_identity',
+        requesterExternalUserId: undefined,
+        requesterChatId: externalChatId,
+      };
+    }
   }
 
   // ── Approval interception (gated behind feature flag) ──
@@ -431,6 +467,7 @@ export async function handleChannelInbound(
       bearerToken,
       orchestrator: runOrchestrator,
       guardianCtx,
+      assistantId,
     });
 
     if (approvalResult.handled) {
@@ -503,6 +540,7 @@ export async function handleChannelInbound(
         replyCallbackUrl,
         bearerToken,
         guardianCtx,
+        assistantId,
       });
     } else {
       // Fire-and-forget: process the message and deliver the reply in the background.
@@ -599,6 +637,22 @@ const RUN_POLL_MAX_WAIT_MS = 300_000; // 5 minutes
 const POST_DECISION_POLL_INTERVAL_MS = 500;
 const POST_DECISION_POLL_MAX_WAIT_MS = RUN_POLL_MAX_WAIT_MS;
 
+/**
+ * Override the poll max-wait for tests. When set, used in place of
+ * RUN_POLL_MAX_WAIT_MS so tests can exercise timeout paths without
+ * waiting 5 minutes.
+ */
+let testPollMaxWaitOverride: number | null = null;
+
+/** @internal — test-only: set an override for the poll max-wait. */
+export function _setTestPollMaxWait(ms: number | null): void {
+  testPollMaxWaitOverride = ms;
+}
+
+function getEffectivePollMaxWait(): number {
+  return testPollMaxWaitOverride ?? RUN_POLL_MAX_WAIT_MS;
+}
+
 interface ApprovalProcessingParams {
   orchestrator: RunOrchestrator;
   conversationId: string;
@@ -610,6 +664,7 @@ interface ApprovalProcessingParams {
   replyCallbackUrl: string;
   bearerToken?: string;
   guardianCtx: GuardianContext;
+  assistantId: string;
 }
 
 /**
@@ -636,6 +691,7 @@ function processChannelMessageWithApprovals(params: ApprovalProcessingParams): v
     replyCallbackUrl,
     bearerToken,
     guardianCtx,
+    assistantId,
   } = params;
 
   const isNonGuardian = guardianCtx.actorRole === 'non-guardian';
@@ -656,9 +712,10 @@ function processChannelMessageWithApprovals(params: ApprovalProcessingParams): v
       // Poll the run until it reaches a terminal state, delivering approval
       // prompts when it transitions to needs_confirmation.
       const startTime = Date.now();
+      const pollMaxWait = getEffectivePollMaxWait();
       let lastStatus = run.status;
 
-      while (Date.now() - startTime < RUN_POLL_MAX_WAIT_MS) {
+      while (Date.now() - startTime < pollMaxWait) {
         await new Promise((resolve) => setTimeout(resolve, RUN_POLL_INTERVAL_MS));
 
         const current = orchestrator.getRun(run.id);
@@ -668,12 +725,15 @@ function processChannelMessageWithApprovals(params: ApprovalProcessingParams): v
           const pending = getPendingConfirmationsByConversation(conversationId);
 
           if (isUnverifiedChannel && pending.length > 0) {
-            // No guardian binding — auto-deny the sensitive action (fail-closed).
+            // Unverified channel — auto-deny the sensitive action (fail-closed).
             handleChannelDecision(conversationId, { action: 'reject', source: 'plain_text' }, orchestrator);
+            const denialText = guardianCtx.denialReason === 'no_identity'
+              ? `The action "${pending[0].toolName}" requires guardian approval, but your identity could not be determined. The action has been denied. Please ensure your messaging client sends user identity information.`
+              : `The action "${pending[0].toolName}" requires guardian approval, but no guardian has been set up for this channel. The action has been denied. Please ask an administrator to configure a guardian.`;
             try {
               await deliverChannelReply(replyCallbackUrl, {
                 chatId: externalChatId,
-                text: `The action "${pending[0].toolName}" requires guardian approval, but no guardian has been set up for this channel. The action has been denied. Please ask an administrator to configure a guardian.`,
+                text: denialText,
               }, bearerToken);
             } catch (err) {
               log.error({ err, runId: run.id }, 'Failed to deliver unverified-channel denial notice');
@@ -691,6 +751,7 @@ function processChannelMessageWithApprovals(params: ApprovalProcessingParams): v
             const approvalReqRecord = createApprovalRequest({
               runId: run.id,
               conversationId,
+              assistantId,
               channel: sourceChannel,
               requesterExternalUserId: guardianCtx.requesterExternalUserId ?? '',
               requesterChatId: guardianCtx.requesterChatId ?? externalChatId,
@@ -765,7 +826,14 @@ function processChannelMessageWithApprovals(params: ApprovalProcessingParams): v
                   bearerToken,
                 );
               } catch (err) {
-                log.error({ err, runId: run.id }, 'Failed to deliver approval prompt for channel run');
+                // Fail-closed: if we cannot deliver the approval prompt, the
+                // user will never see it and the run would hang indefinitely
+                // in needs_confirmation. Auto-deny to avoid silent wait states.
+                log.error(
+                  { err, runId: run.id, conversationId },
+                  'Failed to deliver standard approval prompt; auto-denying (fail-closed)',
+                );
+                handleChannelDecision(conversationId, { action: 'reject', source: 'plain_text' }, orchestrator);
               }
             }
           }
@@ -792,8 +860,19 @@ function processChannelMessageWithApprovals(params: ApprovalProcessingParams): v
 
         channelDeliveryStore.markProcessed(eventId);
 
-        // Deliver the final assistant reply to the requester's chat
-        await deliverReplyViaCallback(conversationId, externalChatId, replyCallbackUrl, bearerToken);
+        // Deliver the final assistant reply exactly once. The post-decision
+        // poll in schedulePostDecisionDelivery races with this path; the
+        // claimRunDelivery guard ensures only the winner sends the reply.
+        // If delivery fails, release the claim so the other poller can retry
+        // rather than permanently losing the reply.
+        if (channelDeliveryStore.claimRunDelivery(run.id)) {
+          try {
+            await deliverReplyViaCallback(conversationId, externalChatId, replyCallbackUrl, bearerToken);
+          } catch (deliveryErr) {
+            channelDeliveryStore.resetRunDeliveryClaim(run.id);
+            throw deliveryErr;
+          }
+        }
 
         // If this was a non-guardian run that went through guardian approval,
         // also notify the guardian's chat about the outcome.
@@ -823,7 +902,7 @@ function processChannelMessageWithApprovals(params: ApprovalProcessingParams): v
         // needs_secret, or disappeared). Record a processing failure so the
         // retry/dead-letter machinery can handle it.
         const timeoutErr = new Error(
-          `Approval poll timeout: run did not reach terminal state within ${RUN_POLL_MAX_WAIT_MS}ms (status: ${finalRun?.status ?? 'null'})`,
+          `Approval poll timeout: run did not reach terminal state within ${pollMaxWait}ms (status: ${finalRun?.status ?? 'null'})`,
         );
         log.warn(
           { runId: run.id, status: finalRun?.status, conversationId },
@@ -853,6 +932,7 @@ interface ApprovalInterceptionParams {
   bearerToken?: string;
   orchestrator: RunOrchestrator;
   guardianCtx: GuardianContext;
+  assistantId: string;
 }
 
 interface ApprovalInterceptionResult {
@@ -884,6 +964,7 @@ async function handleApprovalInterception(
     bearerToken,
     orchestrator,
     guardianCtx,
+    assistantId,
   } = params;
 
   // ── Guardian approval decision path ──
@@ -909,14 +990,14 @@ async function handleApprovalInterception(
     // the decision resolves to exactly the right approval even when
     // multiple approvals target the same guardian chat.
     let guardianApproval = decision?.runId
-      ? getPendingApprovalByRunAndGuardianChat(decision.runId, sourceChannel, externalChatId)
+      ? getPendingApprovalByRunAndGuardianChat(decision.runId, sourceChannel, externalChatId, assistantId)
       : null;
 
     // For plain-text decisions (no run ID), check how many pending
     // approvals exist for this guardian chat. If there are multiple,
     // the guardian must use buttons to disambiguate.
     if (!guardianApproval && decision && !decision.runId) {
-      const allPending = getAllPendingApprovalsByGuardianChat(sourceChannel, externalChatId);
+      const allPending = getAllPendingApprovalsByGuardianChat(sourceChannel, externalChatId, assistantId);
       if (allPending.length > 1) {
         try {
           await deliverChannelReply(replyCallbackUrl, {
@@ -936,7 +1017,7 @@ async function handleApprovalInterception(
     // Fall back to the single-result lookup for non-decision messages
     // (reminder path) or when the scoped lookup found nothing.
     if (!guardianApproval && !decision) {
-      guardianApproval = getPendingApprovalByGuardianChat(sourceChannel, externalChatId);
+      guardianApproval = getPendingApprovalByGuardianChat(sourceChannel, externalChatId, assistantId);
     }
 
     if (guardianApproval) {
@@ -1056,16 +1137,19 @@ async function handleApprovalInterception(
   const pendingPrompt = getChannelApprovalPrompt(conversationId);
   if (!pendingPrompt) return { handled: false };
 
-  // When the sender is from an unverified channel (no guardian binding),
-  // auto-deny any pending confirmation and block self-approval.
+  // When the sender is from an unverified channel, auto-deny any pending
+  // confirmation and block self-approval.
   if (guardianCtx.actorRole === 'unverified_channel') {
     const pending = getPendingConfirmationsByConversation(conversationId);
     if (pending.length > 0) {
       handleChannelDecision(conversationId, { action: 'reject', source: 'plain_text' }, orchestrator);
+      const denialText = guardianCtx.denialReason === 'no_identity'
+        ? `The action "${pending[0].toolName}" requires guardian approval, but your identity could not be determined. The action has been denied.`
+        : `The action "${pending[0].toolName}" requires guardian approval, but no guardian has been set up for this channel. The action has been denied.`;
       try {
         await deliverChannelReply(replyCallbackUrl, {
           chatId: externalChatId,
-          text: `The action "${pending[0].toolName}" requires guardian approval, but no guardian has been set up for this channel. The action has been denied.`,
+          text: denialText,
         }, bearerToken);
       } catch (err) {
         log.error({ err, conversationId }, 'Failed to deliver unverified-channel denial notice during interception');
@@ -1153,8 +1237,8 @@ async function handleApprovalInterception(
     // Schedule a background poll for run terminal state and deliver the reply.
     // This handles the case where the original poll in
     // processChannelMessageWithApprovals has already exited due to timeout.
-    // If the original poll is still running and delivers first, the duplicate
-    // delivery is acceptable (gateway deduplicates or user sees a repeat).
+    // The claimRunDelivery guard ensures at-most-once delivery when both
+    // pollers race to terminal state.
     if (result.applied && result.runId) {
       schedulePostDecisionDelivery(
         orchestrator,
@@ -1201,9 +1285,9 @@ async function handleApprovalInterception(
  * handles the case where the original poll in `processChannelMessageWithApprovals`
  * has already exited due to the 5-minute timeout.
  *
- * If the original poll already delivered the reply, delivering it again is
- * acceptable — the gateway will deduplicate or the user sees a duplicate
- * (better than seeing nothing).
+ * Uses the same `claimRunDelivery` guard as the main poll to guarantee
+ * at-most-once delivery: whichever poller reaches terminal state first
+ * claims the delivery, and the other silently skips it.
  */
 function schedulePostDecisionDelivery(
   orchestrator: RunOrchestrator,
@@ -1221,7 +1305,14 @@ function schedulePostDecisionDelivery(
         const current = orchestrator.getRun(runId);
         if (!current) break;
         if (current.status === 'completed' || current.status === 'failed') {
-          await deliverReplyViaCallback(conversationId, externalChatId, replyCallbackUrl, bearerToken);
+          if (channelDeliveryStore.claimRunDelivery(runId)) {
+            try {
+              await deliverReplyViaCallback(conversationId, externalChatId, replyCallbackUrl, bearerToken);
+            } catch (deliveryErr) {
+              channelDeliveryStore.resetRunDeliveryClaim(runId);
+              throw deliveryErr;
+            }
+          }
           return;
         }
       }

package/src/skills/clawhub.ts

@@ -163,6 +163,8 @@ export interface ClawhubSearchResultItem {
   installs: number;
   version: string;
   createdAt: number;
+  /** Where this skill comes from: "vellum" (first-party) or "clawhub" (community). */
+  source: 'vellum' | 'clawhub';
 }
 
 export interface ClawhubSearchResult {
@@ -273,10 +275,10 @@ export async function clawhubSearch(query: string): Promise<ClawhubSearchResult>
     try {
       const parsed = JSON.parse(result.stdout);
       if (Array.isArray(parsed)) {
-        return { skills: parsed };
+        return { skills: parsed.map((s: ClawhubSearchResultItem) => ({ ...s, source: s.source ?? 'clawhub' as const })) };
       }
       if (parsed.skills && Array.isArray(parsed.skills)) {
-        return parsed as ClawhubSearchResult;
+        return { skills: parsed.skills.map((s: ClawhubSearchResultItem) => ({ ...s, source: s.source ?? 'clawhub' as const })) };
       }
     } catch {
       // CLI outputs text: "slug vVersion  DisplayName  (score)"
@@ -296,6 +298,7 @@ export async function clawhubSearch(query: string): Promise<ClawhubSearchResult>
           stars: 0,
           installs: 0,
           createdAt: 0,
+          source: 'clawhub',
         });
       }
     }
@@ -330,6 +333,7 @@ export async function clawhubExplore(opts?: { limit?: number; sort?: string }):
         installs: (item.stats as Record<string, number>)?.installsAllTime ?? 0,
         version: (item.tags as Record<string, string>)?.latest ?? '',
         createdAt: (item.createdAt as number) ?? 0,
+        source: 'clawhub',
       }));
       return { skills };
     } catch {

package/src/subagent/manager.ts

@@ -482,10 +482,13 @@ export class SubagentManager {
     let message: string;
 
     if (outcome === 'completed') {
+      const silent = config.sendResultToUser === false;
       message =
         `[Subagent "${config.label}" completed]\n\n` +
         `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.`;
+        (silent
+          ? `This subagent was spawned for internal processing. Read the result for your own use but do NOT share it with the user.\nDo NOT re-spawn this subagent.`
+          : `Do NOT re-spawn this subagent — just read and share the results.`);
     } else {
       const error = managed.state.error ?? 'Unknown error';
       message =

package/src/subagent/types.ts

@@ -42,6 +42,8 @@ export interface SubagentConfig {
   systemPromptOverride?: string;
   /** Optional skill IDs to pre-activate on the subagent session. */
   preactivatedSkillIds?: string[];
+  /** Whether the parent should present the result to the user. Defaults to true. */
+  sendResultToUser?: boolean;
 }
 
 // ── State (runtime) ─────────────────────────────────────────────────────

package/src/tools/skills/vellum-catalog.ts

@@ -15,7 +15,7 @@ function getVellumSkillsDir(): string {
   return join(import.meta.dir, '..', '..', 'config', 'vellum-skills');
 }
 
-interface CatalogEntry {
+export interface CatalogEntry {
   id: string;
   name: string;
   description: string;
@@ -88,7 +88,7 @@ function parseCatalogEntry(directory: string): CatalogEntry | null {
   }
 }
 
-function listCatalogEntries(): CatalogEntry[] {
+export function listCatalogEntries(): CatalogEntry[] {
   const catalogDir = getVellumSkillsDir();
   if (!existsSync(catalogDir)) return [];
 
@@ -107,6 +107,49 @@ function listCatalogEntries(): CatalogEntry[] {
   return entries.sort((a, b) => a.id.localeCompare(b.id));
 }
 
+/**
+ * Install a skill from the vellum-skills catalog by ID.
+ * Returns { success, skillName, error }.
+ */
+export function installFromVellumCatalog(skillId: string): { success: boolean; skillName?: string; error?: string } {
+  const catalogDir = getVellumSkillsDir();
+  const skillDir = join(catalogDir, skillId.trim());
+  const skillFilePath = join(skillDir, 'SKILL.md');
+
+  if (!existsSync(skillFilePath)) {
+    return { success: false, error: `Skill "${skillId}" not found in the Vellum catalog` };
+  }
+
+  const content = readFileSync(skillFilePath, 'utf-8');
+  const match = content.match(FRONTMATTER_REGEX);
+  if (!match) {
+    return { success: false, error: `Skill "${skillId}" has invalid SKILL.md` };
+  }
+
+  const entry = parseCatalogEntry(skillDir);
+  if (!entry) {
+    return { success: false, error: `Skill "${skillId}" has invalid SKILL.md` };
+  }
+
+  const bodyMarkdown = content.slice(match[0].length);
+  const result = createManagedSkill({
+    id: entry.id,
+    name: entry.name,
+    description: entry.description,
+    bodyMarkdown,
+    emoji: entry.emoji,
+    includes: entry.includes,
+    overwrite: true,
+    addToIndex: true,
+  });
+
+  if (!result.created) {
+    return { success: false, error: result.error };
+  }
+
+  return { success: true, skillName: entry.id };
+}
+
 class VellumSkillsCatalogTool implements Tool {
   name = 'vellum_skills_catalog';
   description = 'List and install Vellum-provided skills from the first-party catalog';

package/src/tools/subagent/spawn.ts

@@ -8,6 +8,7 @@ export async function executeSubagentSpawn(
   const label = input.label as string;
   const objective = input.objective as string;
   const extraContext = input.context as string | undefined;
+  const sendResultToUser = input.send_result_to_user !== false;
 
   if (!label || !objective) {
     return { content: 'Both "label" and "objective" are required.', isError: true };
@@ -26,6 +27,7 @@ export async function executeSubagentSpawn(
         label,
         objective,
         context: extraContext,
+        sendResultToUser,
       },
       sendToClient as (msg: unknown) => void,
     );