@vellumai/assistant 0.3.2 → 0.3.4

package/src/calls/call-orchestrator.ts

@@ -8,6 +8,7 @@
 
 import Anthropic from '@anthropic-ai/sdk';
 import { getConfig } from '../config/loader.js';
+import { resolveUserReference } from '../config/user-reference.js';
 import { getLogger } from '../util/logger.js';
 import {
   getCallSession,
@@ -43,6 +44,8 @@ export class CallOrchestrator {
   private task: string | null;
   /** Instructions queued while an LLM turn is in-flight or during waiting_on_user */
   private pendingInstructions: string[] = [];
+  /** Monotonic run id used to suppress stale turn side effects after interruption. */
+  private llmRunVersion = 0;
 
   constructor(callSessionId: string, relay: RelayConnection, task: string | null) {
     this.callSessionId = callSessionId;
@@ -64,20 +67,30 @@ export class CallOrchestrator {
    * Handle a final caller utterance from the ConversationRelay.
    */
   async handleCallerUtterance(transcript: string, speaker?: PromptSpeakerContext): Promise<void> {
+    const interruptedInFlight = this.state === 'processing' || this.state === 'speaking';
     // If we're already processing or speaking, abort the in-flight generation
-    if (this.state === 'processing' || this.state === 'speaking') {
+    if (interruptedInFlight) {
       this.abortController.abort();
       this.abortController = new AbortController();
     }
 
     this.state = 'processing';
     this.resetSilenceTimer();
-
-    // Append caller utterance
-    this.conversationHistory.push({
-      role: 'user',
-      content: this.formatCallerUtterance(transcript, speaker),
-    });
+    const callerContent = this.formatCallerUtterance(transcript, speaker);
+
+    // Preserve strict role alternation for Anthropic. If the last message
+    // is already user-role (e.g. interrupted run never appended assistant,
+    // or a second caller prompt arrives before assistant completion), merge
+    // this utterance into that same user turn.
+    const lastMessage = this.conversationHistory[this.conversationHistory.length - 1];
+    if (lastMessage?.role === 'user') {
+      lastMessage.content = `${lastMessage.content}\n${callerContent}`;
+    } else {
+      this.conversationHistory.push({
+        role: 'user',
+        content: callerContent,
+      });
+    }
 
     await this.runLlm();
   }
@@ -168,8 +181,15 @@ export class CallOrchestrator {
    * Handle caller interrupting the assistant's speech.
    */
   handleInterrupt(): void {
+    const wasSpeaking = this.state === 'speaking';
     this.abortController.abort();
     this.abortController = new AbortController();
+    this.llmRunVersion++;
+    // Explicitly terminate the in-progress TTS turn so the relay can
+    // immediately hand control back to the caller after barge-in.
+    if (wasSpeaking) {
+      this.relay.sendTextToken('', true);
+    }
     this.state = 'idle';
   }
 
@@ -196,13 +216,14 @@ export class CallOrchestrator {
       : '1. Begin the conversation naturally.';
 
     return [
-      'You are on a live phone call on behalf of your user.',
+      `You are on a live phone call on behalf of ${resolveUserReference()}.`,
       this.task ? `Task: ${this.task}` : '',
       '',
       'You are speaking directly to the person who answered the phone.',
       'Respond naturally and conversationally — speak as you would in a real phone conversation.',
       '',
       'IMPORTANT RULES:',
+      '0. When introducing yourself, refer to yourself as an assistant. Avoid the phrase "AI assistant" unless directly asked.',
       disclosureRule,
       '2. Be concise — phone conversations should be brief and natural.',
       '3. If the callee asks something you don\'t know, include [ASK_USER: your question here] in your response along with a hold message like "Let me check on that for you."',
@@ -239,6 +260,8 @@ export class CallOrchestrator {
     }
 
     const client = new Anthropic({ apiKey });
+    const runVersion = ++this.llmRunVersion;
+    const runSignal = this.abortController.signal;
 
     try {
       this.state = 'speaking';
@@ -255,7 +278,7 @@ export class CallOrchestrator {
             content: m.content,
           })),
         },
-        { signal: this.abortController.signal },
+        { signal: runSignal },
       );
 
       // Buffer incoming tokens so we can strip control markers ([ASK_USER:...], [END_CALL])
@@ -264,6 +287,7 @@ export class CallOrchestrator {
       let ttsBuffer = '';
 
       const flushSafeText = (_force: boolean): void => {
+        if (!this.isCurrentRun(runVersion)) return;
         if (ttsBuffer.length === 0) return;
         const bracketIdx = ttsBuffer.indexOf('[');
         if (bracketIdx === -1) {
@@ -312,6 +336,7 @@ export class CallOrchestrator {
       };
 
       stream.on('text', (text) => {
+        if (!this.isCurrentRun(runVersion)) return;
         ttsBuffer += text;
 
         // If the buffer contains a complete control marker, strip it
@@ -326,6 +351,7 @@ export class CallOrchestrator {
       });
 
       const finalMessage = await stream.finalMessage();
+      if (!this.isCurrentRun(runVersion)) return;
 
       // Final sweep: strip any remaining control markers from the buffer
       ttsBuffer = ttsBuffer.replace(ASK_USER_REGEX, '').replace(END_CALL_MARKER, '');
@@ -412,8 +438,25 @@ export class CallOrchestrator {
       this.flushPendingInstructions();
     } catch (err: unknown) {
       // Aborted requests are expected (interruptions, rapid utterances)
-      if (err instanceof Error && err.name === 'AbortError') {
-        log.debug({ callSessionId: this.callSessionId }, 'LLM request aborted');
+      if (this.isExpectedAbortError(err) || runSignal.aborted) {
+        log.debug(
+          {
+            callSessionId: this.callSessionId,
+            errName: err instanceof Error ? err.name : typeof err,
+            stale: !this.isCurrentRun(runVersion),
+          },
+          'LLM request aborted',
+        );
+        if (this.isCurrentRun(runVersion)) {
+          this.state = 'idle';
+        }
+        return;
+      }
+      if (!this.isCurrentRun(runVersion)) {
+        log.debug(
+          { callSessionId: this.callSessionId, errName: err instanceof Error ? err.name : typeof err },
+          'Ignoring stale LLM streaming error from superseded turn',
+        );
         return;
       }
       log.error({ err, callSessionId: this.callSessionId }, 'LLM streaming error');
@@ -423,6 +466,15 @@ export class CallOrchestrator {
     }
   }
 
+  private isExpectedAbortError(err: unknown): boolean {
+    if (!(err instanceof Error)) return false;
+    return err.name === 'AbortError' || err.name === 'APIUserAbortError';
+  }
+
+  private isCurrentRun(runVersion: number): boolean {
+    return runVersion === this.llmRunVersion;
+  }
+
   /**
    * Drain any instructions that were queued while the LLM was active.
    * Each instruction is appended as a user message (now correctly after

package/src/calls/twilio-config.ts

@@ -16,8 +16,17 @@ export interface TwilioConfig {
 export function getTwilioConfig(): TwilioConfig {
   const accountSid = getSecureKey('credential:twilio:account_sid');
   const authToken = getSecureKey('credential:twilio:auth_token');
-  const phoneNumber = process.env.TWILIO_PHONE_NUMBER || getSecureKey('credential:twilio:phone_number') || '';
   const config = loadConfig();
+
+  // Phone number resolution priority:
+  // 1. TWILIO_PHONE_NUMBER env var (explicit override)
+  // 2. config file sms.phoneNumber (primary storage)
+  // 3. credential:twilio:phone_number secure key (backward-compat fallback)
+  const phoneNumber =
+    process.env.TWILIO_PHONE_NUMBER ||
+    config.sms?.phoneNumber ||
+    getSecureKey('credential:twilio:phone_number') ||
+    '';
   const webhookBaseUrl = getPublicBaseUrl(config);
 
   // Always use the centralized relay URL derived from the public ingress base URL.

package/src/calls/twilio-rest.ts

@@ -154,3 +154,73 @@ export async function provisionPhoneNumber(
     capabilities: { voice: data.capabilities.voice, sms: data.capabilities.sms },
   };
 }
+
+export interface WebhookUrls {
+  voiceUrl: string;
+  statusCallbackUrl: string;
+  smsUrl: string;
+}
+
+/**
+ * Update the webhook URLs on a Twilio IncomingPhoneNumber.
+ *
+ * Configures voice webhook, voice status callback, and SMS webhook so
+ * that Twilio routes inbound calls and messages to the assistant's
+ * gateway endpoints.
+ */
+export async function updatePhoneNumberWebhooks(
+  accountSid: string,
+  authToken: string,
+  phoneNumber: string,
+  webhooks: WebhookUrls,
+): Promise<void> {
+  // First, find the SID for this phone number
+  const listRes = await fetch(
+    `${twilioBaseUrl(accountSid)}/IncomingPhoneNumbers.json?PhoneNumber=${encodeURIComponent(phoneNumber)}`,
+    {
+      method: 'GET',
+      headers: { Authorization: twilioAuthHeader(accountSid, authToken) },
+    },
+  );
+
+  if (!listRes.ok) {
+    const text = await listRes.text();
+    throw new Error(`Twilio API error ${listRes.status} looking up phone number: ${text}`);
+  }
+
+  const listData = (await listRes.json()) as {
+    incoming_phone_numbers: Array<{ sid: string; phone_number: string }>;
+  };
+
+  const match = listData.incoming_phone_numbers.find((n) => n.phone_number === phoneNumber);
+  if (!match) {
+    throw new Error(`Phone number ${phoneNumber} not found on Twilio account ${accountSid}`);
+  }
+
+  // Update the phone number's webhook configuration
+  const body = new URLSearchParams({
+    VoiceUrl: webhooks.voiceUrl,
+    VoiceMethod: 'POST',
+    StatusCallback: webhooks.statusCallbackUrl,
+    StatusCallbackMethod: 'POST',
+    SmsUrl: webhooks.smsUrl,
+    SmsMethod: 'POST',
+  });
+
+  const updateRes = await fetch(
+    `${twilioBaseUrl(accountSid)}/IncomingPhoneNumbers/${match.sid}.json`,
+    {
+      method: 'POST',
+      headers: {
+        Authorization: twilioAuthHeader(accountSid, authToken),
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: body.toString(),
+    },
+  );
+
+  if (!updateRes.ok) {
+    const text = await updateRes.text();
+    throw new Error(`Twilio API error ${updateRes.status} updating webhooks: ${text}`);
+  }
+}

package/src/cli/map.ts

@@ -166,6 +166,12 @@ async function startLearnSession(
           continue;
         }
 
+        if (m.type === 'ride_shotgun_progress') {
+          // Live progress from auto-navigator
+          process.stderr.write(`  ${m.message}\n`);
+          continue;
+        }
+
         if (m.type === 'ride_shotgun_result') {
           clearTimeout(timeoutHandle);
           socket.destroy();

package/src/commands/__tests__/cc-command-registry.test.ts

@@ -276,6 +276,73 @@ describe('summary extraction', () => {
     expect(entry!.summary).toBe('');
   });
 
+  test('returns empty summary when frontmatter is truncated by partial read', () => {
+    // Simulate frontmatter that exceeds SUMMARY_READ_BYTES (1024).
+    // The closing --- delimiter will be cut off, causing FRONTMATTER_REGEX to
+    // fail. extractSummary should return '' instead of '---'.
+    const largeFrontmatter = '---\n' + 'key: ' + 'x'.repeat(1100) + '\n---\n\nActual summary.';
+    createCommandsDir(tmpDir, {
+      'big-frontmatter.md': largeFrontmatter,
+    });
+
+    const registry = discoverCCCommands(tmpDir);
+    const entry = registry.entries.get('big-frontmatter');
+    expect(entry).toBeDefined();
+    expect(entry!.summary).toBe('');
+  });
+
+  test('returns empty summary when frontmatter is truncated (CRLF)', () => {
+    const largeFrontmatter = '---\r\n' + 'key: ' + 'x'.repeat(1100) + '\r\n---\r\n\r\nActual summary.';
+    createCommandsDir(tmpDir, {
+      'big-frontmatter-crlf.md': largeFrontmatter,
+    });
+
+    const registry = discoverCCCommands(tmpDir);
+    const entry = registry.entries.get('big-frontmatter-crlf');
+    expect(entry).toBeDefined();
+    expect(entry!.summary).toBe('');
+  });
+
+  test('returns empty summary when frontmatter is truncated with multibyte UTF-8 characters', () => {
+    // When frontmatter contains multibyte UTF-8 characters (e.g., CJK text),
+    // the JavaScript string length (UTF-16 code units) is smaller than the
+    // byte length. The truncation guard must compare byte length, not
+    // string length, against SUMMARY_READ_BYTES (1024).
+    //
+    // Each CJK character is 3 bytes in UTF-8 but 1 code unit in UTF-16.
+    // We need the total byte count to reach 1024 while string length stays
+    // well below 1024 to exercise the bug.
+    const cjkChars = '\u4e00'.repeat(340); // 340 chars * 3 bytes = 1020 bytes
+    // '---\n' is 4 bytes, so total = 4 + 1020 = 1024 bytes, but string
+    // length = 4 + 340 = 344 chars — well under 1024.
+    const truncatedContent = '---\n' + cjkChars;
+    createCommandsDir(tmpDir, {
+      'multibyte-frontmatter.md': truncatedContent,
+    });
+
+    const registry = discoverCCCommands(tmpDir);
+    const entry = registry.entries.get('multibyte-frontmatter');
+    expect(entry).toBeDefined();
+    // Should return '' because the frontmatter opening delimiter is present
+    // but the closing delimiter is missing and the byte length reached the
+    // read limit — indicating truncation.
+    expect(entry!.summary).toBe('');
+  });
+
+  test('returns summary for small file starting with thematic break ---', () => {
+    // A small markdown file that starts with "---" as a thematic break (not
+    // frontmatter) should still have its first content line extracted as a
+    // summary, rather than being treated as truncated frontmatter.
+    createCommandsDir(tmpDir, {
+      'thematic-break.md': '---\nThis is a valid summary after a thematic break.',
+    });
+
+    const registry = discoverCCCommands(tmpDir);
+    const entry = registry.entries.get('thematic-break');
+    expect(entry).toBeDefined();
+    expect(entry!.summary).toBe('This is a valid summary after a thematic break.');
+  });
+
   test('handles frontmatter with Windows-style line endings', () => {
     createCommandsDir(tmpDir, {
       'crlf.md': '---\r\ntitle: Test\r\n---\r\n\r\nSummary with CRLF.',

package/src/commands/cc-command-registry.ts

@@ -1,5 +1,6 @@
 import { closeSync, existsSync, openSync, readdirSync, readFileSync, readSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
+import { FRONTMATTER_REGEX } from '../skills/frontmatter.js';
 import { getLogger } from '../util/logger.js';
 
 const log = getLogger('cc-commands');
@@ -27,7 +28,6 @@ export interface CCCommandRegistry {
 // ─── Constants ───────────────────────────────────────────────────────────────
 
 const COMMAND_NAME_REGEX = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
-const FRONTMATTER_REGEX = /^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/;
 const DEFAULT_CACHE_TTL_MS = 30_000;
 const MAX_SUMMARY_LENGTH = 100;
 
@@ -80,6 +80,19 @@ function extractSummary(content: string): string {
   const fmMatch = content.match(FRONTMATTER_REGEX);
   if (fmMatch) {
     body = content.slice(fmMatch[0].length);
+  } else if (/^---\r?\n/.test(content)) {
+    if (Buffer.byteLength(content, 'utf-8') >= SUMMARY_READ_BYTES) {
+      // Content starts with a frontmatter opening delimiter but the closing
+      // delimiter was not found. The content length reached SUMMARY_READ_BYTES,
+      // so the read was likely truncated — the missing closing `---` is
+      // probably just beyond the read boundary. Return empty rather than
+      // surfacing partial frontmatter fields as a summary.
+      return '';
+    }
+    // Small file that starts with `---` (thematic break or unclosed
+    // frontmatter opener). Skip the leading `---` line and extract the
+    // first real content line from the remainder.
+    body = content.replace(/^---\r?\n/, '');
   }
 
   // Find first non-empty line

package/src/config/bundled-skills/claude-code/TOOLS.json

@@ -11,7 +11,15 @@
         "properties": {
           "prompt": {
             "type": "string",
-            "description": "The coding task or question for Claude Code to work on"
+            "description": "The coding task or question for Claude Code to work on. Use this for free-form tasks. Mutually exclusive with command."
+          },
+          "command": {
+            "type": "string",
+            "description": "Name of a .claude/commands/*.md command template to execute. The template will be loaded and $ARGUMENTS substituted before execution. Use this instead of prompt when invoking a named CC command."
+          },
+          "arguments": {
+            "type": "string",
+            "description": "Arguments to substitute into the command template ($ARGUMENTS placeholder). Only used with the command input."
           },
           "working_dir": {
             "type": "string",
@@ -30,8 +38,7 @@
             "enum": ["general", "researcher", "coder", "reviewer"],
             "description": "Worker profile that scopes tool access. Defaults to general (backward compatible)."
           }
-        },
-        "required": ["prompt"]
+        }
       },
       "executor": "tools/claude-code.ts",
       "execution_target": "host"

package/src/config/bundled-skills/email-setup/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: "Email Setup"
+description: "Create the assistant's own email address via the Vellum hosted API (one-time setup)"
+user-invocable: true
+metadata: {"vellum": {"emoji": "📧"}}
+---
+
+You are setting up your own personal email address. This is a one-time operation — once you have an email, you do not need to run this again.
+
+## Prerequisites
+
+Only proceed if the user explicitly asks you to create or set up your email address. Do NOT proactively run this skill.
+
+## Step 1: Check if Email Already Exists
+
+Before doing anything, check whether you already have an email address configured:
+
+```bash
+vellum email status
+```
+
+This will return your email address, the callback URL that inbound email will hit, and the path to the inbox locally. If you already have an email address, tell the user your existing email address and stop — do NOT create another one.
+
+## Step 2: Create Your Email
+
+Call the Vellum hosted API to provision your email. Use `host_bash` to make the request:
+
+```bash
+vellum email create <your-username>
+```
+
+For `<your-username>`, use your assistant name (lowercased, alphanumeric only). Check your identity from `IDENTITY.md` or `USER.md` to determine your name. If you don't have a name yet, ask the user what username they'd like for your email.
+
+## Step 3: Confirm Setup
+
+After the inbox is created successfully:
+
+1. Parse the command output to extract your new email address.
+2. Tell the user your new email address.
+3. Store a note in your memory or `USER.md` that your email has been provisioned so you remember it in future conversations.
+
+## Rules
+
+- **One-time only.** If an inbox already exists (Step 1), do not create another. Inform the user of the existing address.
+- **User-initiated only.** Never run this skill unless the user asks you to set up or create an email.
+- **No custom domains.** Use the default provider domain. Do not attempt domain setup.
+- **No API key prompting.** The email API key should already be configured. If the `vellum email` command fails with an API key error, tell the user the email integration is not yet configured and ask them to set it up.
+
+## Troubleshooting
+
+### API key not configured
+If you get an error about a missing API key, the email provider has not been set up. Tell the user:
+> "Email isn't configured yet. Please set up the email integration first."
+
+### Inbox creation failed
+If inbox creation returns an error (e.g. username taken), try a variation of the name (append a number or use a nickname) and retry once. If it still fails, report the error to the user.

package/src/config/bundled-skills/messaging/SKILL.md

@@ -39,6 +39,8 @@ Telegram uses a bot token (not OAuth). Install and load the **telegram-setup** s
 
 The telegram-setup skill handles: verifying the bot token from @BotFather, generating a webhook secret, registering bot commands, and storing credentials securely via the secure credential prompt flow. **Never accept a Telegram bot token pasted in plaintext chat — always use the secure prompt.** Webhook registration with Telegram is handled automatically by the gateway on startup and whenever credentials change.
 
+The telegram-setup skill also includes **guardian verification**, which links your Telegram account as the trusted guardian for the bot.
+
 ### SMS (Twilio)
 SMS messaging uses Twilio as the telephony provider. Twilio credentials and phone number configuration are shared with the **phone-calls** skill. Load the **twilio-setup** skill to configure Twilio:
    - Call `vellum_skills_catalog` with `action: "install"` and `skill_id: "twilio-setup"`.
@@ -47,6 +49,8 @@ SMS messaging uses Twilio as the telephony provider. Twilio credentials and phon
 
 The twilio-setup skill handles: credential storage (Account SID + Auth Token), phone number provisioning or assignment, and public ingress setup. Once Twilio is configured, SMS is available automatically — no additional feature flag is needed. The assistant's Twilio phone number is used for both outbound SMS and voice calls.
 
+The twilio-setup skill also includes optional **guardian verification** for SMS, which links your phone number as the trusted guardian. This is the same guardian concept used by Telegram — it ensures only verified users can approve sensitive operations via SMS.
+
 ## Platform Selection
 
 - If the user specifies a platform (e.g., "check my Slack"), pass it as the `platform` parameter.

package/src/config/bundled-skills/subagent/SKILL.md

@@ -18,6 +18,10 @@ Subagents follow this status flow: `pending` -> `running` -> `completed` / `fail
 
 Only the parent session that spawned a subagent can interact with it (check status, send messages, abort, or read output).
 
+## Silent Mode
+
+Set `send_result_to_user: false` when spawning a subagent whose result is for internal processing only. The parent will still be notified on completion, but the notification will instruct it to read the result without presenting it to the user.
+
 ## Tips
 
 - Do NOT poll `subagent_status` in a loop. You will be notified automatically when a subagent completes.

package/src/config/bundled-skills/subagent/TOOLS.json

@@ -20,6 +20,10 @@
           "context": {
             "type": "string",
             "description": "Optional additional context to pass to the subagent"
+          },
+          "send_result_to_user": {
+            "type": "boolean",
+            "description": "Whether to present the subagent's result to the user when it completes. Defaults to true. Set to false for internal/silent processing."
           }
         },
         "required": ["label", "objective"]

package/src/config/defaults.ts

@@ -224,7 +224,7 @@ export const DEFAULT_CONFIG: AssistantConfig = {
     userConsultTimeoutSeconds: 120,
     disclosure: {
       enabled: true,
-      text: 'At the very beginning of the call, disclose that you are an AI assistant calling on behalf of the user.',
+      text: 'At the very beginning of the call, introduce yourself as an assistant calling on behalf of the user.',
     },
     safety: {
       denyCategories: [],

package/src/config/schema.ts

@@ -907,7 +907,7 @@ export const CallsDisclosureConfigSchema = z.object({
     .default(true),
   text: z
     .string({ error: 'calls.disclosure.text must be a string' })
-    .default('At the very beginning of the call, disclose that you are an AI assistant calling on behalf of the user.'),
+    .default('At the very beginning of the call, introduce yourself as an assistant calling on behalf of the user.'),
 });
 
 export const CallsSafetyConfigSchema = z.object({
@@ -1017,7 +1017,7 @@ export const CallsConfigSchema = z.object({
     .default(120),
   disclosure: CallsDisclosureConfigSchema.default({
     enabled: true,
-    text: 'At the very beginning of the call, disclose that you are an AI assistant calling on behalf of the user.',
+    text: 'At the very beginning of the call, introduce yourself as an assistant calling on behalf of the user.',
   }),
   safety: CallsSafetyConfigSchema.default({
     denyCategories: [],
@@ -1066,6 +1066,9 @@ export const SmsConfigSchema = z.object({
   phoneNumber: z
     .string({ error: 'sms.phoneNumber must be a string' })
     .default(''),
+  assistantPhoneNumbers: z
+    .record(z.string(), z.string({ error: 'sms.assistantPhoneNumbers values must be strings' }))
+    .optional(),
 });
 
 const IngressBaseSchema = z.object({
@@ -1337,7 +1340,7 @@ export const AssistantConfigSchema = z.object({
     userConsultTimeoutSeconds: 120,
     disclosure: {
       enabled: true,
-      text: 'At the very beginning of the call, disclose that you are an AI assistant calling on behalf of the user.',
+      text: 'At the very beginning of the call, introduce yourself as an assistant calling on behalf of the user.',
     },
     safety: {
       denyCategories: [],

package/src/config/skills.ts

@@ -5,13 +5,12 @@ import { getConfig } from './loader.js';
 import { getWorkspaceSkillsDir } from '../util/platform.js';
 import { getLogger } from '../util/logger.js';
 import { stripCommentLines } from './system-prompt.js';
+import { parseFrontmatterFields } from '../skills/frontmatter.js';
 import { parseToolManifestFile } from '../skills/tool-manifest.js';
 import { computeSkillVersionHash } from '../skills/version-hash.js';
 
 const log = getLogger('skills');
 
-const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
-
 // ─── New interfaces for extended skill metadata ──────────────────────────────
 
 export interface VellumMetadata {
@@ -266,39 +265,13 @@ function parseIncludes(raw: string | undefined, skillFilePath: string): string[]
 }
 
 function parseFrontmatter(content: string, skillFilePath: string): ParsedFrontmatter | null {
-  const match = content.match(FRONTMATTER_REGEX);
-  if (!match) {
+  const result = parseFrontmatterFields(content);
+  if (!result) {
     log.warn({ skillFilePath }, 'Skipping skill without YAML frontmatter');
     return null;
   }
 
-  const frontmatter = match[1];
-  const fields: Record<string, string> = {};
-  for (const line of frontmatter.split(/\r?\n/)) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith('#')) continue;
-    const separatorIndex = trimmed.indexOf(':');
-    if (separatorIndex === -1) continue;
-
-    const key = trimmed.slice(0, separatorIndex).trim();
-    let value = trimmed.slice(separatorIndex + 1).trim();
-    const isDoubleQuoted = value.startsWith('"') && value.endsWith('"');
-    const isSingleQuoted = value.startsWith('\'') && value.endsWith('\'');
-    if (isDoubleQuoted || isSingleQuoted) {
-      value = value.slice(1, -1);
-      if (isDoubleQuoted) {
-        // Unescape sequences produced by buildSkillMarkdown's esc().
-        // Only for double-quoted values — single-quoted YAML treats backslashes literally.
-        // Single-pass to avoid misinterpreting \\n (escaped backslash + n) as a newline.
-        value = value.replace(/\\(["\\nr])/g, (_, ch) => {
-          if (ch === 'n') return '\n';
-          if (ch === 'r') return '\r';
-          return ch; // handles \\ → \ and \" → "
-        });
-      }
-    }
-    fields[key] = value;
-  }
+  const { fields, body } = result;
 
   const name = fields.name?.trim();
   const description = fields.description?.trim();
@@ -335,7 +308,7 @@ function parseFrontmatter(content: string, skillFilePath: string): ParsedFrontma
   return {
     name,
     description,
-    body: stripCommentLines(content.slice(match[0].length)),
+    body: stripCommentLines(body),
     homepage,
     userInvocable,
     disableModelInvocation,

package/src/config/system-prompt.ts

@@ -5,6 +5,7 @@ import { getLogger } from '../util/logger.js';
 import { loadSkillCatalog, type SkillSummary } from './skills.js';
 import { getConfig } from './loader.js';
 import { listCredentialMetadata } from '../tools/credentials/metadata-store.js';
+import { resolveUserReference } from './user-reference.js';
 
 const log = getLogger('system-prompt');
 
@@ -116,6 +117,7 @@ export function buildSystemPrompt(): string {
   parts.push(buildToolPermissionSection());
   parts.push(buildSystemPermissionSection());
   parts.push(buildChannelAwarenessSection());
+  parts.push(buildExternalCommsIdentitySection());
   parts.push(buildSwarmGuidanceSection());
   parts.push(buildAccessPreferenceSection());
   parts.push(buildIntegrationSection());
@@ -378,6 +380,20 @@ export function buildChannelAwarenessSection(): string {
   ].join('\n');
 }
 
+export function buildExternalCommsIdentitySection(): string {
+  const userRef = resolveUserReference();
+  return [
+    '## External Communications Identity',
+    '',
+    'When communicating with people outside your user\'s household (phone calls, messages to non-guardian contacts, emails to third parties, etc.):',
+    '',
+    `- Refer to yourself as an **assistant**, not an "AI assistant" or "artificial intelligence". Keep identity framing simple and natural.`,
+    `- When introducing who you represent, say you are acting on behalf of **${userRef}**.`,
+    '- Do not volunteer that you are an AI unless directly asked. If asked, answer honestly.',
+    '- This is guidance for natural, human-like communication — not a hard constraint. Occasional variations are acceptable.',
+  ].join('\n');
+}
+
 export function buildSwarmGuidanceSection(): string {
   return [
     '## Parallel Task Orchestration',