@vellumai/assistant 0.4.4 → 0.4.6

package/src/calls/call-pointer-message-composer.ts

@@ -1,17 +1,10 @@
 /**
- * Layered call pointer message composition system.
+ * Deterministic call pointer message templates and instruction builder.
  *
- * Generates pointer/status copy through a priority chain:
- *   1. Generator-produced text (when provided by daemon and audience is trusted)
- *   2. Deterministic fallback templates (preserving existing semantics)
- *
- * Follows the same pattern as approval-message-composer.ts and
- * guardian-action-message-composer.ts.
+ * Provides fallback templates for untrusted audiences and builds
+ * structured instructions for the daemon session to generate pointer
+ * copy as a natural conversation turn for trusted audiences.
  */
-import type { PointerCopyGenerator } from '../runtime/http-types.js';
-import { getLogger } from '../util/logger.js';
-
-const log = getLogger('call-pointer-message-composer');
 
 // ---------------------------------------------------------------------------
 // Types
@@ -33,83 +26,33 @@ export interface CallPointerMessageContext {
   channel?: string;
 }
 
-export interface ComposeCallPointerMessageOptions {
-  fallbackText?: string;
-  requiredFacts?: string[];
-  maxTokens?: number;
-  timeoutMs?: number;
-}
-
-// ---------------------------------------------------------------------------
-// Constants (exported for the daemon-injected generator implementation)
-// ---------------------------------------------------------------------------
-
-export const POINTER_COPY_TIMEOUT_MS = 3_000;
-export const POINTER_COPY_MAX_TOKENS = 120;
-export const POINTER_COPY_SYSTEM_PROMPT =
-  'You are an assistant writing a brief status update about a phone call. '
-  + 'Keep it concise (1-2 sentences), natural, and informative. '
-  + 'Preserve all factual details exactly (phone numbers, durations, failure reasons, verification status). '
-  + 'Do not mention internal systems or technical details. '
-  + 'Return plain text only.';
-
 // ---------------------------------------------------------------------------
-// Public API
+// Daemon instruction builder
 // ---------------------------------------------------------------------------
 
 /**
- * Compose pointer copy using the daemon-injected generator when available,
- * with deterministic fallback for reliability.
- *
- * The generator parameter is the daemon-provided function that knows about
- * providers. When absent (or in test env), only the deterministic fallback
- * is used.
+ * Build an instruction message to send to the daemon session so the
+ * assistant generates a natural pointer status update as a conversation turn.
  */
-export async function composeCallPointerMessageGenerative(
-  context: CallPointerMessageContext,
-  options: ComposeCallPointerMessageOptions = {},
-  generator?: PointerCopyGenerator,
-): Promise<string> {
-  const fallbackText = options.fallbackText?.trim() || getPointerFallbackMessage(context);
-
-  if (process.env.NODE_ENV === 'test') {
-    return fallbackText;
-  }
-
-  if (generator) {
-    try {
-      const generated = await generator(context, options);
-      if (generated) return generated;
-    } catch (err) {
-      log.warn({ err, scenario: context.scenario }, 'Failed to generate pointer copy, using fallback');
-    }
-  }
-
-  return fallbackText;
-}
-
-/** @internal Exported for use by the daemon-injected generator implementation. */
-export function buildPointerGenerationPrompt(
-  context: CallPointerMessageContext,
-  fallbackText: string,
-  requiredFacts: string[] | undefined,
-): string {
-  const factClause = requiredFacts && requiredFacts.length > 0
-    ? `Required facts to include: ${requiredFacts.join(', ')}.\n`
-    : '';
-  return [
-    'Rewrite the following call status message as a natural, conversational update.',
-    'Keep the same concrete facts (phone number, duration, failure reason, verification status).',
-    factClause,
-    `Context JSON: ${JSON.stringify(context)}`,
-    `Fallback message: ${fallbackText}`,
-  ].filter(Boolean).join('\n\n');
-}
-
-/** @internal Exported for use by the daemon-injected generator implementation. */
-export function includesRequiredFacts(text: string, requiredFacts: string[] | undefined): boolean {
-  if (!requiredFacts || requiredFacts.length === 0) return true;
-  return requiredFacts.every((fact) => text.includes(fact));
+export function buildPointerInstruction(context: CallPointerMessageContext): string {
+  const parts: string[] = [
+    '[CALL_STATUS_EVENT]',
+    `Event: ${context.scenario}`,
+    `Phone number: ${context.phoneNumber}`,
+  ];
+  if (context.duration) parts.push(`Duration: ${context.duration}`);
+  if (context.reason) parts.push(`Reason: ${context.reason}`);
+  if (context.verificationCode) parts.push(`Verification code: ${context.verificationCode}`);
+  if (context.channel) parts.push(`Channel: ${context.channel}`);
+
+  parts.push('');
+  parts.push(
+    'Write a brief (1-2 sentence) status update about this phone call event for the user. '
+    + 'Preserve all factual details exactly (phone numbers, durations, failure reasons, verification codes). '
+    + 'Be concise, natural, and informative.',
+  );
+
+  return parts.join('\n');
 }
 
 // ---------------------------------------------------------------------------
@@ -119,8 +62,7 @@ export function includesRequiredFacts(text: string, requiredFacts: string[] | un
 /**
  * Return a scenario-specific deterministic fallback message.
  *
- * These preserve the exact semantics of the original hard-coded pointer
- * templates from call-pointer-messages.ts.
+ * Used for untrusted audiences and when the daemon processor is unavailable.
  */
 export function getPointerFallbackMessage(context: CallPointerMessageContext): string {
   switch (context.scenario) {

package/src/calls/call-pointer-messages.ts

@@ -3,17 +3,17 @@
  * so the user sees call lifecycle events without the full transcript
  * (which lives in the dedicated voice conversation).
  *
- * Trust-aware: trusted audiences receive assistant-generated copy when a
- * generator is available; untrusted/unknown audiences always receive
- * deterministic fallback text.
+ * Trust-aware: trusted audiences get pointer messages routed through the
+ * daemon session as a conversation turn (the assistant generates the text).
+ * Untrusted/unknown audiences always receive deterministic fallback text
+ * written directly to the conversation store.
  */
 
 import * as conversationStore from '../memory/conversation-store.js';
-import type { PointerCopyGenerator } from '../runtime/http-types.js';
 import { getLogger } from '../util/logger.js';
 import {
+  buildPointerInstruction,
   type CallPointerMessageContext,
-  composeCallPointerMessageGenerative,
   getPointerFallbackMessage,
 } from './call-pointer-message-composer.js';
 
@@ -23,24 +23,40 @@ export type PointerEvent = 'started' | 'completed' | 'failed' | 'guardian_verifi
 
 export type PointerAudienceMode = 'auto' | 'trusted' | 'untrusted';
 
+/**
+ * Daemon-injected function that sends a message through the daemon session
+ * pipeline (persistAndProcessMessage), letting the assistant generate the
+ * pointer text as a natural conversation turn.
+ *
+ * @param requiredFacts - facts that must appear verbatim in the generated
+ *   text (phone number, duration, outcome keyword, etc.). The processor
+ *   should validate the output and throw if any are missing so the
+ *   deterministic fallback fires.
+ */
+export type PointerMessageProcessor = (
+  conversationId: string,
+  instruction: string,
+  requiredFacts?: string[],
+) => Promise<void>;
+
 // ---------------------------------------------------------------------------
-// Module-level generator injection (set by daemon lifecycle at startup)
+// Module-level processor injection (set by daemon lifecycle at startup)
 // ---------------------------------------------------------------------------
 
-let pointerCopyGenerator: PointerCopyGenerator | undefined;
+let pointerMessageProcessor: PointerMessageProcessor | undefined;
 
 /**
- * Inject the daemon-provided pointer copy generator.
+ * Inject the daemon-provided pointer message processor.
  * Called from daemon/lifecycle.ts at startup, following the same pattern
  * as setRelayBroadcast.
  */
-export function setPointerCopyGenerator(generator: PointerCopyGenerator): void {
-  pointerCopyGenerator = generator;
+export function setPointerMessageProcessor(processor: PointerMessageProcessor): void {
+  pointerMessageProcessor = processor;
 }
 
 /** @internal Reset for tests. */
-export function resetPointerCopyGenerator(): void {
-  pointerCopyGenerator = undefined;
+export function resetPointerMessageProcessor(): void {
+  pointerMessageProcessor = undefined;
 }
 
 // ---------------------------------------------------------------------------
@@ -51,6 +67,7 @@ export function resetPointerCopyGenerator(): void {
  * Resolve whether the audience for a pointer message is trusted.
  *
  * Trusted when:
+ * - recent message provenance trust class is 'guardian' or 'trusted_contact'
  * - conversation threadType is 'private' (local desktop-origin context)
  * - conversation origin channel is 'vellum' (desktop app)
  *
@@ -58,6 +75,12 @@ export function resetPointerCopyGenerator(): void {
  */
 function resolvePointerAudienceTrust(conversationId: string): boolean {
   try {
+    // Check provenance trust class on recent messages first — this catches
+    // trusted contacts who initiate calls from gateway channels (e.g. WhatsApp)
+    // where the conversation itself isn't a desktop-origin private thread.
+    const provenance = conversationStore.getConversationRecentProvenanceTrustClass(conversationId);
+    if (provenance === 'guardian' || provenance === 'trusted_contact') return true;
+
     const threadType = conversationStore.getConversationThreadType(conversationId);
     if (threadType === 'private') return true;
 
@@ -91,6 +114,7 @@ export async function addPointerMessage(
   };
 
   // Build required-facts list so generated text cannot drop key details.
+  // These are passed to the processor for post-generation validation.
   const requiredFacts: string[] = [phoneNumber];
   if (extra?.duration) requiredFacts.push(extra.duration);
   if (extra?.verificationCode) requiredFacts.push(extra.verificationCode);
@@ -109,21 +133,30 @@ export async function addPointerMessage(
   const outcomeKeyword = eventOutcomeKeywords[event];
   if (outcomeKeyword) requiredFacts.push(outcomeKeyword);
 
-  let text: string;
-
-  const isTrusted =
+  const trustedAudience =
     audienceMode === 'trusted' ||
     (audienceMode === 'auto' && resolvePointerAudienceTrust(conversationId));
 
-  if (isTrusted && pointerCopyGenerator) {
-    text = await composeCallPointerMessageGenerative(context, { requiredFacts }, pointerCopyGenerator);
-  } else {
-    if (!isTrusted && pointerCopyGenerator) {
-      log.debug({ event, conversationId }, 'Untrusted audience — using deterministic pointer copy');
+  if (trustedAudience && pointerMessageProcessor) {
+    // Route through the daemon session — the assistant generates the
+    // pointer text as a natural conversation turn, shaped by context,
+    // identity, and preferences.
+    const instruction = buildPointerInstruction(context);
+    try {
+      await pointerMessageProcessor(conversationId, instruction, requiredFacts);
+      return;
+    } catch (err) {
+      log.warn({ err, event, conversationId }, 'Daemon pointer processing failed, falling back to deterministic');
     }
-    text = getPointerFallbackMessage(context);
+  } else if (!trustedAudience && pointerMessageProcessor) {
+    log.debug({ event, conversationId }, 'Untrusted audience — using deterministic pointer copy');
   }
 
+  // Deterministic fallback: write directly to the conversation store.
+  // Used for untrusted audiences, when the daemon processor is unavailable,
+  // or when daemon processing fails.
+  const text = getPointerFallbackMessage(context);
+
   // Pointer messages are assistant-generated status updates in the initiating
   // desktop thread. Do not set userMessageChannel — doing so would mark the
   // conversation's origin channel as voice, causing it to leak into the

package/src/calls/guardian-dispatch.ts

@@ -14,8 +14,10 @@ import {
   listCanonicalGuardianRequests,
   updateCanonicalGuardianDelivery,
 } from '../memory/canonical-guardian-store.js';
+import { getActiveBinding } from '../memory/guardian-bindings.js';
 import { emitNotificationSignal } from '../notifications/emit-signal.js';
 import type { NotificationDeliveryResult } from '../notifications/types.js';
+import { ensureVellumGuardianBinding } from '../runtime/guardian-vellum-migration.js';
 import { getLogger } from '../util/logger.js';
 import { getUserConsultationTimeoutMs } from './call-constants.js';
 import type { CallPendingQuestion } from './types.js';
@@ -88,6 +90,33 @@ async function dispatchGuardianQuestionInner(params: GuardianDispatchParams): Pr
   try {
     const expiresAt = Date.now() + getUserConsultationTimeoutMs();
 
+    // Voice decisions are handled in guardian threads tied to the assistant-
+    // level guardian identity. Resolve the principal from the vellum binding
+    // (the canonical assistant-level binding) so the request is attributed to
+    // the assistant's guardian principal.
+    let vellumBinding = getActiveBinding(assistantId, 'vellum');
+    let guardianPrincipalId = vellumBinding?.guardianPrincipalId ?? undefined;
+
+    // Self-heal: if the vellum binding is missing or lacks a principal,
+    // bootstrap it so the pending_question request can be attributed.
+    if (!guardianPrincipalId) {
+      log.info(
+        { callSessionId, assistantId, hadBinding: !!vellumBinding },
+        'Vellum binding missing or lacks principal — self-healing for voice dispatch',
+      );
+      const healedPrincipalId = ensureVellumGuardianBinding(assistantId);
+      vellumBinding = getActiveBinding(assistantId, 'vellum');
+      guardianPrincipalId = vellumBinding?.guardianPrincipalId ?? healedPrincipalId;
+    }
+
+    if (!guardianPrincipalId) {
+      log.error(
+        { callSessionId, assistantId },
+        'Voice guardian dispatch: no guardianPrincipalId after self-heal — cannot create pending_question',
+      );
+      return;
+    }
+
     // Create the canonical guardian request as the primary record.
     const request = createCanonicalGuardianRequest({
       kind: 'pending_question',
@@ -97,6 +126,7 @@ async function dispatchGuardianQuestionInner(params: GuardianDispatchParams): Pr
       callSessionId,
       pendingQuestionId: pendingQuestion.id,
       questionText: pendingQuestion.questionText,
+      guardianPrincipalId,
       toolName,
       inputDigest,
       expiresAt: new Date(expiresAt).toISOString(),

package/src/calls/relay-server.ts

@@ -510,8 +510,8 @@ export class RelayConnection {
     const initialActorTrust = resolveActorTrust({
       assistantId,
       sourceChannel: 'voice',
-      externalChatId: otherPartyNumber,
-      senderExternalUserId: otherPartyNumber || undefined,
+      conversationExternalId: otherPartyNumber,
+      actorExternalId: otherPartyNumber || undefined,
     });
     const initialGuardianContext = toGuardianRuntimeContextFromTrust(initialActorTrust, otherPartyNumber);
 
@@ -561,8 +561,8 @@ export class RelayConnection {
       const actorTrust = resolveActorTrust({
         assistantId,
         sourceChannel: 'voice',
-        externalChatId: msg.from,
-        senderExternalUserId: msg.from || undefined,
+        conversationExternalId: msg.from,
+        actorExternalId: msg.from || undefined,
       });
 
       // Check for a pending voice guardian challenge before the ACL deny
@@ -979,8 +979,8 @@ export class RelayConnection {
           const verifiedActorTrust = resolveActorTrust({
             assistantId: this.guardianChallengeAssistantId,
             sourceChannel: 'voice',
-            externalChatId: this.guardianVerificationFromNumber,
-            senderExternalUserId: this.guardianVerificationFromNumber,
+            conversationExternalId: this.guardianVerificationFromNumber,
+            actorExternalId: this.guardianVerificationFromNumber,
           });
           this.controller.setGuardianContext(
             toGuardianRuntimeContextFromTrust(verifiedActorTrust, this.guardianVerificationFromNumber),
@@ -1153,9 +1153,9 @@ export class RelayConnection {
       const accessResult = notifyGuardianOfAccessRequest({
         canonicalAssistantId: this.accessRequestAssistantId,
         sourceChannel: 'voice',
-        externalChatId: this.accessRequestFromNumber,
-        senderExternalUserId: this.accessRequestFromNumber,
-        senderName: callerName,
+        conversationExternalId: this.accessRequestFromNumber,
+        actorExternalId: this.accessRequestFromNumber,
+        actorDisplayName: callerName,
       });
 
       if (accessResult.notified) {
@@ -1308,8 +1308,8 @@ export class RelayConnection {
     const updatedTrust = resolveActorTrust({
       assistantId,
       sourceChannel: 'voice',
-      externalChatId: fromNumber,
-      senderExternalUserId: fromNumber,
+      conversationExternalId: fromNumber,
+      actorExternalId: fromNumber,
     });
 
     if (this.controller) {
@@ -1583,8 +1583,8 @@ export class RelayConnection {
         const redeemedActorTrust = resolveActorTrust({
           assistantId: this.inviteRedemptionAssistantId,
           sourceChannel: 'voice',
-          externalChatId: this.inviteRedemptionFromNumber,
-          senderExternalUserId: this.inviteRedemptionFromNumber,
+          conversationExternalId: this.inviteRedemptionFromNumber,
+          actorExternalId: this.inviteRedemptionFromNumber,
         });
         this.controller.setGuardianContext(
           toGuardianRuntimeContextFromTrust(redeemedActorTrust, this.inviteRedemptionFromNumber),

package/src/config/system-prompt.ts

@@ -11,7 +11,7 @@ import { getBaseDataDir, getIsContainerized } from './env-registry.js';
 import { getConfig } from './loader.js';
 import { skillFlagKey } from './skill-state.js';
 import { loadSkillCatalog, type SkillSummary } from './skills.js';
-import { resolveUserReference } from './user-reference.js';
+import { resolveUserPronouns, resolveUserReference } from './user-reference.js';
 
 const log = getLogger('system-prompt');
 
@@ -489,16 +489,23 @@ export function buildChannelCommandIntentSection(): string {
 
 export function buildExternalCommsIdentitySection(): string {
   const userRef = resolveUserReference();
-  return [
+  const userPronouns = resolveUserPronouns();
+  const lines = [
     '## 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}**.`,
+  ];
+  if (userPronouns) {
+    lines.push(`- Your user's pronouns are **${userPronouns}**. Use these when referring to your user in the third person.`);
+  }
+  lines.push(
     '- 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');
+  );
+  return lines.join('\n');
 }
 
 export function buildSwarmGuidanceSection(): string {

package/src/config/templates/BOOTSTRAP.md

@@ -33,7 +33,8 @@ Once they respond, follow the remaining steps in order, one at a time:
    - What they do for work (role, field, day-to-day)
    - What they do for fun (hobbies, interests)
    - What tools they rely on daily (apps, platforms, workflows)
-   Weave these into the conversation. Inferred answers are fine when confidence is high. If something is unclear, ask one short follow-up, but don't turn it into an interview. One or two natural exchanges should cover it. If the user declines to share something, respect that and move on (see Privacy below).
+   - Their pronouns (he/him, she/her, they/them, etc.)
+   Weave these into the conversation. Inferred answers are fine when confidence is high — for pronouns, if the user's name is strongly gendered, you can infer with reasonable confidence, but default to they/them if unsure. If something is unclear, ask one short follow-up, but don't turn it into an interview. One or two natural exchanges should cover it. If the user declines to share something, respect that and move on (see Privacy below).
 
 6. **Show them what you can take off their plate.** Based on everything you've learned, present exactly 2 actionable task suggestions. Each should feel specific to this user, not generic. Frame it as: here's what you can hand off to me right now. Avoid language like "let's build automations" or "let's set up workflows." If `ui_show` is available (dashboard channels), show the suggestions as a card with 2 action buttons. Use `surface_type: "card"` with a short title and body, and add one `relay_prompt` action per suggestion. Each action's `data.prompt` should contain a natural-language request the user would say. Example structure:
    ```
@@ -54,18 +55,18 @@ Ask one question at a time. Don't dump a form on them.
 
 ## Privacy
 
-Only the assistant's name is hard-required. Everything else about the user (their name, work role, hobbies, daily tools) is best-effort. Ask naturally, not as a form. If something is unclear, you can ask one short follow-up, but if the user declines or dodges, do not push. Just move on.
+Only the assistant's name is hard-required. Everything else about the user (their name, pronouns, work role, hobbies, daily tools) is best-effort. Ask naturally, not as a form. If something is unclear, you can ask one short follow-up, but if the user declines or dodges, do not push. Just move on.
 
 A field is "resolved" when any of these is true:
 - The user gave an explicit answer
 - You confidently inferred it from conversation
 - The user declined, dodged, or sidestepped it (treat all of these as declined)
 
-When saving to `USER.md`, mark declined fields so you don't re-ask later (e.g., `Work role: declined_by_user`). Inferred values can note the source (e.g., `Daily tools: inferred: Slack, Figma`).
+When saving to `USER.md`, mark declined fields so you don't re-ask later (e.g., `Work role: declined_by_user`). Inferred values can note the source (e.g., `Daily tools: inferred: Slack, Figma`). For pronouns, if inferred from name, note the source (e.g., `Pronouns: inferred: he/him`).
 
 ## Saving What You Learn
 
-Save what you learn as you go. Update `IDENTITY.md` (name, nature, personality, emoji, style tendency) and `USER.md` (their name, how to address them, goals, locale, work role, hobbies, daily tools) using `file_edit`. If the conversation reveals how the user wants you to behave (e.g., "be direct," "don't be too chatty"), save those behavioral guidelines to `SOUL.md` — that file is about your personality and how you operate, not the user's data. Just do it quietly. Don't tell the user which files you're editing or mention tool names.
+Save what you learn as you go. Update `IDENTITY.md` (name, nature, personality, emoji, style tendency) and `USER.md` (their name, pronouns, how to address them, goals, locale, work role, hobbies, daily tools) using `file_edit`. If the conversation reveals how the user wants you to behave (e.g., "be direct," "don't be too chatty"), save those behavioral guidelines to `SOUL.md` — that file is about your personality and how you operate, not the user's data. Just do it quietly. Don't tell the user which files you're editing or mention tool names.
 
 When saving to `IDENTITY.md`, be specific about the tone, energy, and conversational style you discovered during onboarding. This file persists after onboarding, so everything about how you should come across needs to be captured there -- not just your name and emoji, but the full vibe: how you talk, how much energy you bring, whether you're blunt or gentle, funny or serious.
 
@@ -74,7 +75,7 @@ When saving to `IDENTITY.md`, be specific about the tone, energy, and conversati
 Do NOT delete this file until ALL of the following are true:
 - You have a name (hard requirement)
 - You've figured out your vibe and adopted it
-- User detail fields are resolved: name, work role, hobbies/interests, and daily tools. Resolved means the user provided a value, you confidently inferred one, or the user declined/dodged it. All four must be in one of those states.
+- User detail fields are resolved: name, pronouns, work role, hobbies/interests, and daily tools. Resolved means the user provided a value, you confidently inferred one, or the user declined/dodged it. All five must be in one of those states.
 - 2 suggestions shown (via `ui_show` or as text if UI unavailable)
 - The user selected one, deferred both, or typed an alternate direction
 - Home Base has been created silently

package/src/config/templates/USER.md

@@ -17,6 +17,7 @@ _(What do they care about? What projects are they working on? What annoys them?
 _Each field below should end up in one of three states: an explicit value, an inferred value (note the source), or `declined_by_user`. All fields must be resolved before onboarding completes, but declining is a valid resolution._
 
 - Preferred name/reference:
+- Pronouns:
 - Goals:
 - Locale:
 - Work role:

package/src/config/user-reference.ts

@@ -22,3 +22,47 @@ export function resolveUserReference(): string {
 
   return DEFAULT_USER_REFERENCE;
 }
+
+/**
+ * Resolve the user's pronouns from USER.md.  Returns `null` when the
+ * file is missing, the field is empty, or the value is a sentinel like
+ * `declined_by_user`.
+ *
+ * Priority order:
+ *   1. Any `Pronouns:` line outside the Onboarding Snapshot section
+ *      (explicit user update post-onboarding takes precedence).
+ *   2. The structured `- Pronouns:` field inside the Onboarding Snapshot.
+ */
+export function resolveUserPronouns(): string | null {
+  const content = readTextFileSync(getWorkspacePromptPath('USER.md'));
+  if (content == null) return null;
+
+  const snapshotIdx = content.indexOf('## Onboarding Snapshot');
+
+  // 1. Check for a Pronouns line outside the Onboarding Snapshot section.
+  //    This represents an explicit post-onboarding update and takes priority.
+  if (snapshotIdx >= 0) {
+    const beforeSnapshot = content.slice(0, snapshotIdx);
+    const outsideMatch = beforeSnapshot.match(/Pronouns:[ \t]*(.*)/);
+    if (outsideMatch && outsideMatch[1].trim()) {
+      return cleanPronounValue(outsideMatch[1].trim());
+    }
+  }
+
+  // 2. Fall back to the structured field in the Onboarding Snapshot.
+  if (snapshotIdx >= 0) {
+    const section = content.slice(snapshotIdx);
+    const match = section.match(/^- Pronouns:[ \t]*(.*)/m);
+    if (match && match[1].trim()) {
+      return cleanPronounValue(match[1].trim());
+    }
+  }
+
+  return null;
+}
+
+function cleanPronounValue(raw: string): string | null {
+  if (raw === 'declined_by_user') return null;
+  // Strip "inferred: " prefix for clean output
+  return raw.replace(/^inferred:\s*/i, '');
+}

package/src/daemon/handlers/guardian-actions.ts

@@ -3,6 +3,7 @@ import {
 } from '../../approvals/guardian-decision-primitive.js';
 import { getCanonicalGuardianRequest } from '../../memory/canonical-guardian-store.js';
 import type { ApprovalAction } from '../../runtime/channel-approval-types.js';
+import { resolveLocalIpcGuardianContext } from '../../runtime/local-actor-identity.js';
 import { listGuardianDecisionPrompts } from '../../runtime/routes/guardian-action-routes.js';
 import type { GuardianActionDecision, GuardianActionsPendingRequest } from '../ipc-protocol.js';
 import { defineHandlers, log } from './shared.js';
@@ -45,13 +46,15 @@ export const guardianActionsHandlers = defineHandlers({
       }
     }
 
+    // Resolve the local IPC actor's principal via the vellum guardian binding.
+    const localGuardianCtx = resolveLocalIpcGuardianContext('vellum');
     const canonicalResult = await applyCanonicalGuardianDecision({
       requestId: msg.requestId,
       action: msg.action as ApprovalAction,
       actorContext: {
-        externalUserId: undefined,
+        externalUserId: localGuardianCtx.guardianExternalUserId,
         channel: 'vellum',
-        isTrusted: true,
+        guardianPrincipalId: localGuardianCtx.guardianPrincipalId ?? undefined,
       },
       userText: undefined,
     });

package/src/daemon/handlers/sessions.ts

@@ -123,12 +123,14 @@ function makeIpcEventSender(params: {
       });
 
       try {
+        const guardianContext = session.guardianContext;
         createCanonicalGuardianRequest({
           id: event.requestId,
           kind: 'tool_approval',
           sourceType: 'desktop',
           sourceChannel,
           conversationId,
+          guardianPrincipalId: guardianContext?.guardianPrincipalId ?? undefined,
           toolName: event.toolName,
           status: 'pending',
           requestCode: generateCanonicalRequestCode(),
@@ -597,13 +599,16 @@ export async function handleUserMessage(
         ]));
 
         if (pendingRequestIdsForConversation.length > 0) {
+          // Resolve the local IPC actor's principal via the vellum guardian binding
+          // for principal-based authorization in the canonical decision primitive.
+          const localCtx = resolveLocalIpcGuardianContext(ipcChannel);
           const routerResult = await routeGuardianReply({
             messageText: messageText.trim(),
             channel: ipcChannel,
             actor: {
-              externalUserId: undefined,
+              externalUserId: localCtx.guardianExternalUserId,
               channel: ipcChannel,
-              isTrusted: true,
+              guardianPrincipalId: localCtx.guardianPrincipalId ?? undefined,
             },
             conversationId: msg.sessionId,
             pendingRequestIds: pendingRequestIdsForConversation,
@@ -636,7 +641,7 @@ export async function handleUserMessage(
               assistantMessageChannel: ipcChannel,
               userMessageInterface: ipcInterface,
               assistantMessageInterface: ipcInterface,
-              provenanceActorRole: 'guardian' as const,
+              provenanceTrustClass: 'guardian' as const,
             };
 
             const consumedUserMessage = createUserMessage(messageText, msg.attachments ?? []);