@vellumai/assistant 0.3.27 → 0.4.0

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

@@ -8,10 +8,10 @@
  *   POST   /v1/ingress/members/:id/block — block a member
  *
  * Invites:
- *   GET    /v1/ingress/invites           — list invites
- *   POST   /v1/ingress/invites           — create an invite
- *   DELETE /v1/ingress/invites/:id       — revoke an invite
- *   POST   /v1/ingress/invites/redeem    — redeem an invite
+ *   GET    /v1/ingress/invites        — list invites
+ *   POST   /v1/ingress/invites        — create an invite (supports voice)
+ *   DELETE /v1/ingress/invites/:id    — revoke an invite
+ *   POST   /v1/ingress/invites/redeem — redeem an invite (token or voice code)
  */
 
 import {
@@ -20,6 +20,7 @@ import {
   listIngressInvites,
   listIngressMembers,
   redeemIngressInvite,
+  redeemVoiceInviteCode,
   revokeIngressInvite,
   revokeIngressMember,
   upsertIngressMember,
@@ -130,6 +131,11 @@ export function handleListInvites(url: URL): Response {
 
 /**
  * POST /v1/ingress/invites
+ *
+ * For voice invites, pass `sourceChannel: "voice"` with required
+ * `expectedExternalUserId` (E.164 phone). Voice codes are always 6 digits.
+ * The response will include a one-time `voiceCode` field that must be
+ * communicated to the invited user out-of-band.
  */
 export async function handleCreateInvite(req: Request): Promise<Response> {
   const body = (await req.json()) as Record<string, unknown>;
@@ -139,6 +145,8 @@ export async function handleCreateInvite(req: Request): Promise<Response> {
     note: body.note as string | undefined,
     maxUses: body.maxUses as number | undefined,
     expiresInMs: body.expiresInMs as number | undefined,
+    expectedExternalUserId: body.expectedExternalUserId as string | undefined,
+    voiceCodeDigits: body.voiceCodeDigits as number | undefined,
   });
 
   if (!result.ok) {
@@ -161,10 +169,50 @@ export function handleRevokeInvite(inviteId: string): Response {
 
 /**
  * POST /v1/ingress/invites/redeem
+ *
+ * Unified invite redemption endpoint. Supports two modes:
+ *
+ * 1. **Token-based** (existing): pass `token`, `sourceChannel`, `externalUserId`, etc.
+ * 2. **Voice code** (new): pass `code` and `callerExternalUserId` (E.164 phone).
+ *    Optionally pass `assistantId`.
+ *
+ * The presence of `code` in the body selects voice-code redemption.
  */
 export async function handleRedeemInvite(req: Request): Promise<Response> {
   const body = (await req.json()) as Record<string, unknown>;
 
+  // Voice-code redemption path: triggered when `code` is present
+  if (body.code != null) {
+    const callerExternalUserId = body.callerExternalUserId as string | undefined;
+    const code = body.code as string | undefined;
+
+    if (!callerExternalUserId || !code) {
+      return Response.json(
+        { ok: false, error: 'callerExternalUserId and code are required' },
+        { status: 400 },
+      );
+    }
+
+    const result = redeemVoiceInviteCode({
+      assistantId: body.assistantId as string | undefined,
+      callerExternalUserId,
+      sourceChannel: 'voice',
+      code,
+    });
+
+    if (!result.ok) {
+      return Response.json({ ok: false, error: result.reason }, { status: 400 });
+    }
+
+    return Response.json({
+      ok: true,
+      type: result.type,
+      memberId: result.memberId,
+      ...(result.type === 'redeemed' ? { inviteId: result.inviteId } : {}),
+    });
+  }
+
+  // Token-based redemption path (default)
   const result = redeemIngressInvite({
     token: body.token as string | undefined,
     externalUserId: body.externalUserId as string | undefined,

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

@@ -75,6 +75,9 @@ export async function handlePairingRequest(req: Request, ctx: PairingHandlerCont
 
     const result = ctx.pairingStore.beginRequest({ pairingRequestId, pairingSecret, deviceId, deviceName });
     if (!result.ok) {
+      if (result.reason === 'already_paired') {
+        return httpError('CONFLICT', 'This pairing request is already bound to another device', 409);
+      }
       const statusCode = result.reason === 'invalid_secret' ? 403 : result.reason === 'not_found' ? 403 : 410;
       return httpError('FORBIDDEN', 'Forbidden', statusCode);
     }

package/src/runtime/tool-grant-request-helper.ts

@@ -0,0 +1,195 @@
+/**
+ * Tool grant request creation and guardian notification helper.
+ *
+ * Encapsulates the "create/dedupe canonical tool_grant_request + emit notification"
+ * logic so non-guardian channel actors can escalate tool invocations that require
+ * guardian approval. Modeled after the access-request-helper pattern.
+ *
+ * Invariants preserved:
+ * - Unverified actors are fail-closed (caller must gate before calling).
+ * - Guardians cannot self-approve (grant minting uses guardian identity).
+ * - Notification routing goes through emitNotificationSignal().
+ */
+
+import type { ChannelId } from '../channels/types.js';
+import {
+  createCanonicalGuardianDelivery,
+  createCanonicalGuardianRequest,
+  listCanonicalGuardianRequests,
+} from '../memory/canonical-guardian-store.js';
+import { emitNotificationSignal } from '../notifications/emit-signal.js';
+import { getLogger } from '../util/logger.js';
+import { getGuardianBinding } from './channel-guardian-service.js';
+import { GUARDIAN_APPROVAL_TTL_MS } from './routes/channel-route-shared.js';
+
+const log = getLogger('tool-grant-request-helper');
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ToolGrantRequestParams {
+  assistantId: string;
+  sourceChannel: ChannelId;
+  conversationId: string;
+  requesterExternalUserId: string;
+  requesterChatId?: string;
+  requesterIdentifier?: string;
+  toolName: string;
+  inputDigest: string;
+  questionText: string;
+}
+
+export type ToolGrantRequestResult =
+  | { created: true; requestId: string; requestCode: string | null }
+  | { deduped: true; requestId: string; requestCode: string | null }
+  | { failed: true; reason: 'no_guardian_binding' | 'missing_identity' };
+
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Create/dedupe a canonical tool_grant_request and emit a notification signal
+ * so the guardian can approve or deny the tool invocation.
+ *
+ * Returns a result indicating whether a new request was created, an existing
+ * one was deduped, or the escalation failed (no binding, missing identity).
+ */
+export function createOrReuseToolGrantRequest(
+  params: ToolGrantRequestParams,
+): ToolGrantRequestResult {
+  const {
+    assistantId,
+    sourceChannel,
+    conversationId,
+    requesterExternalUserId,
+    requesterChatId,
+    requesterIdentifier,
+    toolName,
+    inputDigest,
+    questionText,
+  } = params;
+
+  if (!requesterExternalUserId) {
+    return { failed: true, reason: 'missing_identity' };
+  }
+
+  const binding = getGuardianBinding(assistantId, sourceChannel);
+  if (!binding) {
+    log.debug(
+      { sourceChannel, assistantId },
+      'No guardian binding for tool grant request escalation',
+    );
+    return { failed: true, reason: 'no_guardian_binding' };
+  }
+
+  // Deduplicate: skip creation if there is already a pending canonical request
+  // for the same requester + conversation + tool + input digest + guardian.
+  // Guardian identity is included so that after a guardian rebind, old requests
+  // tied to the previous guardian don't block creation of a new approvable request.
+  const existing = listCanonicalGuardianRequests({
+    status: 'pending',
+    requesterExternalUserId,
+    conversationId,
+    kind: 'tool_grant_request',
+    toolName,
+  });
+  const dedupeMatch = existing.find(
+    (r) => r.inputDigest === inputDigest && r.guardianExternalUserId === binding.guardianExternalUserId,
+  );
+  if (dedupeMatch) {
+    log.debug(
+      {
+        sourceChannel,
+        requesterExternalUserId,
+        toolName,
+        existingId: dedupeMatch.id,
+      },
+      'Skipping duplicate tool grant request notification',
+    );
+    return { deduped: true, requestId: dedupeMatch.id, requestCode: dedupeMatch.requestCode };
+  }
+
+  const senderLabel = requesterIdentifier || requesterExternalUserId;
+  const requestId = `tool-grant-${assistantId}-${sourceChannel}-${requesterExternalUserId}-${Date.now()}`;
+
+  const canonicalRequest = createCanonicalGuardianRequest({
+    id: requestId,
+    kind: 'tool_grant_request',
+    sourceType: 'channel',
+    sourceChannel,
+    conversationId,
+    requesterExternalUserId,
+    requesterChatId: requesterChatId ?? undefined,
+    guardianExternalUserId: binding.guardianExternalUserId,
+    toolName,
+    inputDigest,
+    questionText,
+    expiresAt: new Date(Date.now() + GUARDIAN_APPROVAL_TTL_MS).toISOString(),
+  });
+
+  // Emit notification so guardian is alerted. Uses 'guardian.question' as
+  // sourceEventName so that existing request-code guidance in the notification
+  // pipeline is preserved.
+  const signalPromise = emitNotificationSignal({
+    sourceEventName: 'guardian.question',
+    sourceChannel,
+    sourceSessionId: conversationId,
+    assistantId,
+    attentionHints: {
+      requiresAction: true,
+      urgency: 'high',
+      isAsyncBackground: false,
+      visibleInSourceNow: false,
+    },
+    contextPayload: {
+      requestId: canonicalRequest.id,
+      requestCode: canonicalRequest.requestCode,
+      sourceChannel,
+      requesterExternalUserId,
+      requesterChatId: requesterChatId ?? null,
+      requesterIdentifier: senderLabel,
+      toolName,
+      questionText,
+    },
+    dedupeKey: `tool-grant-request:${canonicalRequest.id}`,
+    onThreadCreated: (info) => {
+      createCanonicalGuardianDelivery({
+        requestId: canonicalRequest.id,
+        destinationChannel: 'vellum',
+        destinationConversationId: info.conversationId,
+      });
+    },
+  });
+
+  // Record deliveries from the notification pipeline results (fire-and-forget).
+  void signalPromise.then((signalResult) => {
+    for (const result of signalResult.deliveryResults) {
+      if (result.channel === 'vellum') continue; // handled in onThreadCreated
+      if (result.channel !== 'telegram' && result.channel !== 'sms') continue;
+      createCanonicalGuardianDelivery({
+        requestId: canonicalRequest.id,
+        destinationChannel: result.channel,
+        destinationChatId: result.destination.length > 0 ? result.destination : undefined,
+      });
+    }
+  });
+
+  log.info(
+    {
+      sourceChannel,
+      requesterExternalUserId,
+      toolName,
+      requestId: canonicalRequest.id,
+      requestCode: canonicalRequest.requestCode,
+    },
+    'Guardian notified of tool grant request',
+  );
+
+  return {
+    created: true,
+    requestId: canonicalRequest.id,
+    requestCode: canonicalRequest.requestCode,
+  };
+}

package/src/tools/executor.ts

@@ -13,6 +13,7 @@ import { resolveExecutionTarget } from './execution-target.js';
 import { executeWithTimeout,safeTimeoutMs } from './execution-timeout.js';
 import { PermissionChecker } from './permission-checker.js';
 import { SecretDetectionHandler } from './secret-detection-handler.js';
+import { extractAndSanitize } from './sensitive-output-placeholders.js';
 import { applyEdit } from './shared/filesystem/edit-engine.js';
 import { sandboxPolicy } from './shared/filesystem/path-policy.js';
 import { MAX_FILE_SIZE_BYTES } from './shared/filesystem/size-guard.js';
@@ -182,6 +183,15 @@ export class ToolExecutor {
         );
       }
 
+      // Sensitive output extraction: strip directives, replace raw values
+      // with placeholders, and attach bindings for agent-loop substitution.
+      // Runs before secret detection so that raw sensitive values are already
+      // replaced and won't trigger entropy-based redaction.
+      const { sanitizedContent, bindings } = extractAndSanitize(execResult.content);
+      if (bindings.length > 0) {
+        execResult = { ...execResult, content: sanitizedContent, sensitiveBindings: bindings };
+      }
+
       // Secret detection on tool output
       const secretResult = await this.secretDetectionHandler.handle(
         execResult, name, input, context, executionTarget,
@@ -193,6 +203,8 @@ export class ToolExecutor {
       execResult = secretResult.result;
 
       const durationMs = Date.now() - startTime;
+      // Strip sensitiveBindings from lifecycle event to prevent raw values leaking
+      const { sensitiveBindings: _sb, ...safeResult } = execResult;
       emitLifecycleEvent(context, {
         type: 'executed',
         toolName: name,
@@ -205,7 +217,7 @@ export class ToolExecutor {
         riskLevel,
         decision,
         durationMs,
-        result: execResult,
+        result: safeResult,
       });
 
       void getHookManager().trigger('post-tool-execute', {

package/src/tools/guardian-control-plane-policy.ts

@@ -124,13 +124,13 @@ export function isGuardianControlPlaneInvocation(
 export function enforceGuardianOnlyPolicy(
   toolName: string,
   input: Record<string, unknown>,
-  actorRole: string | undefined,
+  trustClass: string | undefined,
 ): { denied: boolean; reason?: string } {
   if (!isGuardianControlPlaneInvocation(toolName, input)) {
     return { denied: false };
   }
 
-  if (actorRole === 'guardian' || actorRole === undefined) {
+  if (trustClass === 'guardian' || trustClass === undefined) {
     return { denied: false };
   }
 

package/src/tools/sensitive-output-placeholders.ts

@@ -0,0 +1,203 @@
+/**
+ * Sensitive output placeholder extraction and substitution.
+ *
+ * Tool outputs may contain `<vellum-sensitive-output kind="..." value="..." />`
+ * directives. This module:
+ * 1. Parses and strips those directives from tool output.
+ * 2. Replaces any raw sensitive values remaining in the output with stable,
+ *    high-uniqueness placeholders so the LLM never sees the real values.
+ * 3. Returns bindings (placeholder -> real value) for deterministic
+ *    post-generation substitution in the agent loop.
+ *
+ * Raw sensitive values MUST NOT be logged or emitted in lifecycle events.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type SensitiveOutputKind = 'invite_code';
+
+export interface SensitiveOutputBinding {
+  kind: SensitiveOutputKind;
+  placeholder: string;
+  value: string;
+}
+
+// ---------------------------------------------------------------------------
+// Directive regex
+// ---------------------------------------------------------------------------
+
+const DIRECTIVE_RE =
+  /<vellum-sensitive-output\s+kind="([^"]+)"\s+value="([^"]+)"\s*\/>/g;
+
+// ---------------------------------------------------------------------------
+// Placeholder generation
+// ---------------------------------------------------------------------------
+
+const KIND_PREFIX: Record<SensitiveOutputKind, string> = {
+  invite_code: 'VELLUM_ASSISTANT_INVITE_CODE_',
+};
+
+const VALID_KINDS = new Set<string>(Object.keys(KIND_PREFIX));
+
+/**
+ * Generate an 8-char uppercase base-36 short ID.
+ * Provides ~41 bits of entropy — sufficient for intra-request uniqueness.
+ */
+function generateShortId(): string {
+  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+  let id = '';
+  for (let i = 0; i < 8; i++) {
+    id += chars[Math.floor(Math.random() * chars.length)];
+  }
+  return id;
+}
+
+function makePlaceholder(kind: SensitiveOutputKind): string {
+  return `${KIND_PREFIX[kind]}${generateShortId()}`;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface SanitizeResult {
+  sanitizedContent: string;
+  bindings: SensitiveOutputBinding[];
+}
+
+/**
+ * Extract `<vellum-sensitive-output>` directives from tool output content,
+ * strip them, replace any remaining occurrences of the raw sensitive values
+ * with placeholders, and return the bindings for downstream substitution.
+ *
+ * Guarantees:
+ * - Directives are fully removed from the returned content.
+ * - Empty values are silently dropped.
+ * - Duplicate values produce a single binding (same placeholder).
+ * - Unknown kinds are silently ignored.
+ */
+export function extractAndSanitize(content: string): SanitizeResult {
+  const bindings: SensitiveOutputBinding[] = [];
+  const seenValues = new Map<string, SensitiveOutputBinding>();
+
+  // Step 1: parse directives
+  // Reset lastIndex for safety since the regex is global
+  DIRECTIVE_RE.lastIndex = 0;
+  let match: RegExpExecArray | undefined;
+  while ((match = DIRECTIVE_RE.exec(content) ?? undefined) !== undefined) {
+    const kind = match[1];
+    const value = match[2];
+
+    if (!value || value.trim().length === 0) continue;
+    if (!VALID_KINDS.has(kind)) continue;
+
+    const typedKind = kind as SensitiveOutputKind;
+    if (!seenValues.has(value)) {
+      const binding: SensitiveOutputBinding = {
+        kind: typedKind,
+        placeholder: makePlaceholder(typedKind),
+        value,
+      };
+      bindings.push(binding);
+      seenValues.set(value, binding);
+    }
+  }
+
+  if (bindings.length === 0) {
+    return { sanitizedContent: content, bindings: [] };
+  }
+
+  // Step 2: strip directive tags
+  let sanitized = content.replace(DIRECTIVE_RE, '');
+
+  // Step 3: replace raw values with placeholders throughout remaining content
+  for (const binding of bindings) {
+    sanitized = sanitized.split(binding.value).join(binding.placeholder);
+  }
+
+  return { sanitizedContent: sanitized, bindings };
+}
+
+/**
+ * Apply placeholder->value substitution to a text string.
+ * Used by the agent loop to resolve placeholders in streamed deltas
+ * and final message content.
+ */
+export function applySubstitutions(
+  text: string,
+  substitutionMap: ReadonlyMap<string, string>,
+): string {
+  if (substitutionMap.size === 0) return text;
+
+  let result = text;
+  for (const [placeholder, value] of substitutionMap) {
+    result = result.split(placeholder).join(value);
+  }
+  return result;
+}
+
+/**
+ * Chunk-safe substitution for streaming text deltas.
+ *
+ * Because a placeholder like `VELLUM_ASSISTANT_INVITE_CODE_AB12CD34` may be
+ * split across consecutive streamed chunks, this function buffers a trailing
+ * segment that could be the start of an incomplete placeholder and returns it
+ * as `pending`. The caller must prepend `pending` to the next chunk.
+ *
+ * Returns `{ emit, pending }`:
+ * - `emit`: text safe to send to the client (all complete placeholders resolved).
+ * - `pending`: trailing text that might be an incomplete placeholder prefix.
+ */
+export function applyStreamingSubstitution(
+  text: string,
+  substitutionMap: ReadonlyMap<string, string>,
+): { emit: string; pending: string } {
+  if (substitutionMap.size === 0) {
+    return { emit: text, pending: '' };
+  }
+
+  // First, resolve any complete placeholders
+  let resolved = text;
+  for (const [placeholder, value] of substitutionMap) {
+    resolved = resolved.split(placeholder).join(value);
+  }
+
+  // Check if the tail of resolved text could be an incomplete placeholder prefix.
+  // All current placeholders start with "VELLUM_ASSISTANT_".
+  const PREFIX = 'VELLUM_ASSISTANT_';
+  const minSuffixLen = 1; // At minimum, one char of the prefix
+
+  // Walk backwards from the end to find a trailing partial match of any placeholder prefix
+  let pendingStart = resolved.length;
+  for (let i = Math.max(0, resolved.length - getMaxPlaceholderLength(substitutionMap)); i < resolved.length; i++) {
+    const tail = resolved.slice(i);
+    // Check if any placeholder starts with this tail
+    if (tail.length >= minSuffixLen && PREFIX.startsWith(tail)) {
+      pendingStart = i;
+      break;
+    }
+    // Also check if any full placeholder key starts with this tail
+    for (const placeholder of substitutionMap.keys()) {
+      if (placeholder.startsWith(tail) && tail.length < placeholder.length) {
+        pendingStart = i;
+        break;
+      }
+    }
+    if (pendingStart !== resolved.length) break;
+  }
+
+  return {
+    emit: resolved.slice(0, pendingStart),
+    pending: resolved.slice(pendingStart),
+  };
+}
+
+function getMaxPlaceholderLength(map: ReadonlyMap<string, string>): number {
+  let max = 0;
+  for (const key of map.keys()) {
+    if (key.length > max) max = key.length;
+  }
+  return max;
+}

package/src/tools/tool-approval-handler.ts

@@ -1,4 +1,5 @@
 import { consumeGrantForInvocation } from '../approvals/approval-primitive.js';
+import { createOrReuseToolGrantRequest } from '../runtime/tool-grant-request-helper.js';
 import { computeToolApprovalDigest } from '../security/tool-approval-digest.js';
 import { getTaskRunRules } from '../tasks/ephemeral-permissions.js';
 import { getLogger } from '../util/logger.js';
@@ -9,8 +10,8 @@ import type { ExecutionTarget, Tool, ToolContext, ToolExecutionResult, ToolLifec
 
 const log = getLogger('tool-approval-handler');
 
-function isUntrustedGuardianActorRole(role: ToolContext['guardianActorRole']): boolean {
-  return role === 'non-guardian' || role === 'unverified_channel';
+function isUntrustedGuardianTrustClass(role: ToolContext['guardianTrustClass']): boolean {
+  return role === 'trusted_contact' || role === 'unknown';
 }
 
 function requiresGuardianApprovalForActor(
@@ -25,10 +26,10 @@ function requiresGuardianApprovalForActor(
 }
 
 function guardianApprovalDeniedMessage(
-  actorRole: ToolContext['guardianActorRole'],
+  trustClass: ToolContext['guardianTrustClass'],
   toolName: string,
 ): string {
-  if (actorRole === 'unverified_channel') {
+  if (trustClass === 'unknown') {
     return `Permission denied for "${toolName}": this action requires guardian approval from a verified channel identity.`;
   }
   return `Permission denied for "${toolName}": this action requires guardian approval and the current actor is not the guardian.`;
@@ -81,13 +82,13 @@ export class ToolApprovalHandler {
     }
 
     // Reject tool invocations targeting guardian control-plane endpoints from non-guardian actors.
-    const guardianCheck = enforceGuardianOnlyPolicy(name, input, context.guardianActorRole);
+    const guardianCheck = enforceGuardianOnlyPolicy(name, input, context.guardianTrustClass);
     if (guardianCheck.denied) {
       log.warn({
         toolName: name,
         sessionId: context.sessionId,
         conversationId: context.conversationId,
-        actorRole: context.guardianActorRole,
+        trustClass: context.guardianTrustClass,
         reason: 'guardian_only_policy',
       }, 'Guardian-only policy blocked tool invocation');
       const durationMs = Date.now() - startTime;
@@ -117,7 +118,7 @@ export class ToolApprovalHandler {
     let deferredConsumeParams: Parameters<typeof consumeGrantForInvocation>[0] | null = null;
 
     if (
-      isUntrustedGuardianActorRole(context.guardianActorRole)
+      isUntrustedGuardianTrustClass(context.guardianTrustClass)
       && requiresGuardianApprovalForActor(name, input, executionTarget)
     ) {
       const inputDigest = computeToolApprovalDigest(name, input);
@@ -232,7 +233,7 @@ export class ToolApprovalHandler {
           toolName: name,
           sessionId: context.sessionId,
           conversationId: context.conversationId,
-          actorRole: context.guardianActorRole,
+          trustClass: context.guardianTrustClass,
           executionTarget,
           grantId: grantResult.grant.id,
         }, 'Scoped grant consumed — allowing untrusted actor tool invocation');
@@ -266,15 +267,57 @@ export class ToolApprovalHandler {
       }
 
       // No matching grant or race condition — deny.
-      const reason = guardianApprovalDeniedMessage(context.guardianActorRole, name);
+      //
+      // For verified non-guardian actors with sufficient context, escalate to
+      // the guardian by creating a canonical tool_grant_request. Unverified
+      // actors remain fail-closed with no escalation.
+      let escalationMessage: string | undefined;
+      if (
+        context.guardianTrustClass === 'trusted_contact'
+        && context.assistantId
+        && context.executionChannel
+        && context.requesterExternalUserId
+      ) {
+        const inputDigest = deferredConsumeParams?.inputDigest
+          ?? computeToolApprovalDigest(name, input);
+        const escalation = createOrReuseToolGrantRequest({
+          assistantId: context.assistantId,
+          sourceChannel: context.executionChannel as import('../channels/types.js').ChannelId,
+          conversationId: context.conversationId,
+          requesterExternalUserId: context.requesterExternalUserId,
+          requesterChatId: context.requesterChatId,
+          toolName: name,
+          inputDigest,
+          questionText: `Trusted contact is requesting permission to use "${name}"`,
+        });
+
+        if ('created' in escalation) {
+          const codeSuffix = escalation.requestCode
+            ? ` (request code: ${escalation.requestCode})`
+            : '';
+          escalationMessage = `Permission denied for "${name}": this action requires guardian approval. `
+            + `A request has been sent to the guardian${codeSuffix}. `
+            + `Please retry after the guardian approves.`;
+        } else if ('deduped' in escalation) {
+          const codeSuffix = escalation.requestCode
+            ? ` (request code: ${escalation.requestCode})`
+            : '';
+          escalationMessage = `Permission denied for "${name}": guardian approval is already pending${codeSuffix}. `
+            + `Please retry after the guardian approves.`;
+        }
+        // If escalation.failed, fall through to generic denial message.
+      }
+
+      const reason = escalationMessage ?? guardianApprovalDeniedMessage(context.guardianTrustClass, name);
       log.warn({
         toolName: name,
         sessionId: context.sessionId,
         conversationId: context.conversationId,
-        actorRole: context.guardianActorRole,
+        trustClass: context.guardianTrustClass,
         executionTarget,
         reason: 'guardian_approval_required',
         grantMissReason: grantResult.reason,
+        escalated: !!escalationMessage,
       }, 'Guardian approval gate blocked untrusted actor tool invocation (no matching grant)');
       const durationMs = Date.now() - startTime;
       emitLifecycleEvent({