@vellumai/assistant 0.3.3 → 0.3.4

package/src/__tests__/system-prompt.test.ts

@@ -50,8 +50,12 @@ mock.module('../config/loader.js', () => ({
   }),
 }));
 
+mock.module('../config/user-reference.js', () => ({
+  resolveUserReference: () => 'John',
+}));
+
 // Import after mock
-const { buildSystemPrompt, ensurePromptFiles, stripCommentLines } = await import('../config/system-prompt.js');
+const { buildSystemPrompt, ensurePromptFiles, stripCommentLines, buildExternalCommsIdentitySection } = await import('../config/system-prompt.js');
 
 /** Strip the Configuration and Skills sections so base-prompt tests stay focused. */
 function basePrompt(result: string): string {
@@ -167,6 +171,26 @@ describe('buildSystemPrompt', () => {
     expect(result).toContain('Browser automation as last resort');
   });
 
+  test('includes external comms identity section', () => {
+    const result = buildSystemPrompt();
+    expect(result).toContain('## External Communications Identity');
+  });
+
+  test('external comms identity section contains assistant guidance and resolved user reference', () => {
+    const result = buildSystemPrompt();
+    expect(result).toContain('Refer to yourself as an **assistant**');
+    expect(result).toContain('on behalf of **John**');
+  });
+
+  test('buildExternalCommsIdentitySection returns section with expected content', () => {
+    const section = buildExternalCommsIdentitySection();
+    expect(section).toContain('## External Communications Identity');
+    expect(section).toContain('assistant');
+    expect(section).toContain('John');
+    expect(section).toContain('Do not volunteer that you are an AI unless directly asked');
+    expect(section).toContain('Occasional variations are acceptable');
+  });
+
   test('config section uses workspace directory from platform util', () => {
     const result = buildSystemPrompt();
     expect(result).toContain(`Your workspace is mounted at \`/workspace/\` inside the Docker sandbox (host path: \`${TEST_DIR}/\`)`);

package/src/__tests__/tool-executor-lifecycle-events.test.ts

@@ -143,7 +143,12 @@ function makeContext(events: ToolLifecycleEvent[]) {
   };
 }
 
-function makePrompter(promptImpl?: () => Promise<{ decision: 'allow' | 'always_allow' | 'deny' | 'always_deny' }>) {
+function makePrompter(
+  promptImpl?: () => Promise<{
+    decision: 'allow' | 'always_allow' | 'deny' | 'always_deny';
+    decisionContext?: string;
+  }>,
+) {
   return {
     prompt: promptImpl ?? (async () => ({ decision: promptDecision })),
     resolveConfirmation: () => {},
@@ -225,6 +230,34 @@ describe('ToolExecutor lifecycle events', () => {
     expect(deniedEvent.reason).toBe('Permission denied by user');
   });
 
+  test('uses contextual deny messaging when provided by prompter', async () => {
+    checkerDecision = 'prompt';
+    checkerReason = 'guardrail prompt';
+    checkerRisk = 'high';
+    sandboxed = true;
+
+    const events: ToolLifecycleEvent[] = [];
+    const executor = new ToolExecutor(
+      makePrompter(async () => ({
+        decision: 'deny',
+        decisionContext:
+          'Permission denied: this action requires guardian setup before retrying. Explain this and provide setup steps.',
+      })),
+    );
+
+    const result = await executor.execute('bash', { command: 'echo hi' }, makeContext(events));
+
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('requires guardian setup');
+    expect(result.content).not.toContain('Permission denied by user');
+
+    const deniedEvent = events.find((event) => event.type === 'permission_denied');
+    if (!deniedEvent || deniedEvent.type !== 'permission_denied') {
+      throw new Error('Expected permission_denied event');
+    }
+    expect(deniedEvent.reason).toBe('Permission denied (bash): contextual policy');
+  });
+
   test('emits host executionTarget for host tools', async () => {
     const events: ToolLifecycleEvent[] = [];
     const executor = new ToolExecutor(makePrompter());

package/src/__tests__/user-reference.test.ts

@@ -0,0 +1,68 @@
+import { describe, test, expect, mock, beforeEach } from 'bun:test';
+import { join } from 'node:path';
+
+const TEST_DIR = '/tmp/vellum-user-ref-test';
+
+mock.module('../util/platform.js', () => ({
+  getWorkspacePromptPath: (file: string) => join(TEST_DIR, file),
+}));
+
+// Mutable state the tests control
+let mockFileExists = false;
+let mockFileContent = '';
+
+mock.module('node:fs', () => ({
+  existsSync: (path: string) => {
+    if (path === join(TEST_DIR, 'USER.md')) return mockFileExists;
+    return false;
+  },
+  readFileSync: (path: string, _encoding: string) => {
+    if (path === join(TEST_DIR, 'USER.md') && mockFileExists) return mockFileContent;
+    throw new Error(`ENOENT: no such file: ${path}`);
+  },
+}));
+
+// Import after mocks are in place
+const { resolveUserReference } = await import('../config/user-reference.js');
+
+describe('resolveUserReference', () => {
+  beforeEach(() => {
+    mockFileExists = false;
+    mockFileContent = '';
+  });
+
+  test('returns "my human" when USER.md does not exist', () => {
+    mockFileExists = false;
+    expect(resolveUserReference()).toBe('my human');
+  });
+
+  test('returns "my human" when preferred name field is empty', () => {
+    mockFileExists = true;
+    mockFileContent = [
+      '## Onboarding Snapshot',
+      '',
+      '- Preferred name/reference:',
+      '- Goals:',
+      '- Locale:',
+    ].join('\n');
+    expect(resolveUserReference()).toBe('my human');
+  });
+
+  test('returns the configured name when it is set', () => {
+    mockFileExists = true;
+    mockFileContent = [
+      '## Onboarding Snapshot',
+      '',
+      '- Preferred name/reference: John',
+      '- Goals: ship fast',
+      '- Locale: en-US',
+    ].join('\n');
+    expect(resolveUserReference()).toBe('John');
+  });
+
+  test('trims whitespace around the configured name', () => {
+    mockFileExists = true;
+    mockFileContent = '- Preferred name/reference:   Alice   \n';
+    expect(resolveUserReference()).toBe('Alice');
+  });
+});

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/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/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/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: [],
@@ -1340,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',