@vellumai/assistant 0.8.12 → 0.9.0-staging.2

package/src/notifications/guardian-question-mode.ts

@@ -4,13 +4,29 @@
  * Explicit request kinds provide a stable contract between producers and
  * notification rendering logic, avoiding implicit inference from incidental
  * fields like `toolName`.
+ *
+ * Payload shapes are defined as Zod schemas — single source of truth for
+ * both runtime validation and TypeScript types.
+ * https://zod.dev/?id=basic-usage
  */
 
-type GuardianQuestionRequestKind =
-  | "pending_question"
-  | "tool_approval"
-  | "tool_grant_request"
-  | "access_request";
+import { z } from "zod";
+
+import { nonEmpty } from "./notification-utils.js";
+
+// ── Schema primitives ──────────────────────────────────────────────────
+
+export const GuardianQuestionRequestKindSchema = z.enum([
+  "pending_question",
+  "tool_approval",
+  "tool_grant_request",
+  "access_request",
+]);
+
+export type GuardianQuestionRequestKind = z.infer<
+  typeof GuardianQuestionRequestKindSchema
+>;
+
 type GuardianQuestionInstructionMode = "approval" | "answer";
 
 interface GuardianRequestKindModeConfig {
@@ -37,16 +53,82 @@ const REQUEST_KIND_MODE_CONFIG: Record<
   },
 };
 
-interface GuardianQuestionPayloadBase {
-  requestId: string;
-  requestCode: string;
-  questionText: string;
-}
+// ── Zod schemas for guardian.question payloads ──────────────────────────
+
+const GuardianQuestionPayloadBaseSchema = z.object({
+  requestId: z.string().min(1),
+  requestCode: z.string().min(1),
+  questionText: z.string().min(1),
+  /** Channel the request originated from. Set by producers but previously
+   *  invisible to the type system (passed via index signature). */
+  sourceChannel: z.string().optional(),
+  /** Display name or identifier of the requester. */
+  requesterIdentifier: z.string().optional(),
+  /** External user ID of the requester (e.g. Slack user ID). */
+  requesterExternalUserId: z.string().optional(),
+  /** External chat ID of the requester. */
+  requesterChatId: z.string().nullable().optional(),
+});
+
+export const PendingQuestionPayloadSchema =
+  GuardianQuestionPayloadBaseSchema.extend({
+    requestKind: z.literal("pending_question"),
+    callSessionId: z.string().min(1),
+    activeGuardianRequestCount: z.number(),
+    toolName: z.string().optional(),
+  });
 
-interface GuardianQuestionPayloadBaseWithDiscriminator extends GuardianQuestionPayloadBase {
-  requestKind: GuardianQuestionRequestKind;
-  [key: string]: unknown;
-}
+export const ToolApprovalPayloadSchema =
+  GuardianQuestionPayloadBaseSchema.extend({
+    requestKind: z.literal("tool_approval"),
+    toolName: z.string().min(1),
+  });
+
+export const ToolGrantPayloadSchema = GuardianQuestionPayloadBaseSchema.extend({
+  requestKind: z.literal("tool_grant_request"),
+  toolName: z.string().min(1),
+});
+
+export const AccessRequestGuardianPayloadSchema =
+  GuardianQuestionPayloadBaseSchema.extend({
+    requestKind: z.literal("access_request"),
+  });
+
+export const GuardianQuestionPayloadSchema = z.discriminatedUnion(
+  "requestKind",
+  [
+    PendingQuestionPayloadSchema,
+    ToolApprovalPayloadSchema,
+    ToolGrantPayloadSchema,
+    AccessRequestGuardianPayloadSchema,
+  ],
+);
+
+/**
+ * Lenient schema for tool-approval rendering. Requires only `requestKind`
+ * (for mode detection) — everything else is optional. Handles partially
+ * constructed payloads that don't satisfy the strict discriminated union
+ * (e.g. missing `callSessionId` on a `pending_question` with `toolName`).
+ *
+ * Used by `buildToolApprovalSeedContentBlocks` which must degrade
+ * gracefully rather than refuse to render when optional card fields
+ * are absent.
+ */
+export const LenientToolApprovalPayloadSchema = z.object({
+  requestKind: GuardianQuestionRequestKindSchema,
+  requestId: z.string().nullable().optional(),
+  requestCode: z.string().nullable().optional(),
+  questionText: z.string().nullable().optional(),
+  toolName: z.string().nullable().optional(),
+  sourceChannel: z.string().nullable().optional(),
+  requesterIdentifier: z.string().nullable().optional(),
+  requesterExternalUserId: z.string().nullable().optional(),
+  requesterChatId: z.string().nullable().optional(),
+});
+
+export type LenientToolApprovalPayload = z.infer<
+  typeof LenientToolApprovalPayloadSchema
+>;
 
 interface GuardianRequestModeInput {
   kind: unknown;
@@ -105,136 +187,39 @@ const MODE_TEXT_CONFIG: Record<
   },
 };
 
-export interface PendingQuestionGuardianPayload extends GuardianQuestionPayloadBaseWithDiscriminator {
-  requestKind: "pending_question";
-  callSessionId: string;
-  activeGuardianRequestCount: number;
-  /**
-   * Voice tool-approval requests are persisted as pending_question with tool
-   * metadata so they still route through pending-question resolution.
-   */
-  toolName?: string;
-}
-
-export interface ToolApprovalGuardianPayload extends GuardianQuestionPayloadBaseWithDiscriminator {
-  requestKind: "tool_approval";
-  toolName: string;
-}
-
-export interface ToolGrantGuardianPayload extends GuardianQuestionPayloadBaseWithDiscriminator {
-  requestKind: "tool_grant_request";
-  toolName: string;
-}
-
-export interface AccessRequestGuardianPayload extends GuardianQuestionPayloadBaseWithDiscriminator {
-  requestKind: "access_request";
-}
-
-export type GuardianQuestionPayload =
-  | PendingQuestionGuardianPayload
-  | ToolApprovalGuardianPayload
-  | ToolGrantGuardianPayload
-  | AccessRequestGuardianPayload;
+// ── Derived TypeScript types ─────────────────────────────────────────────
+
+export type PendingQuestionGuardianPayload = z.infer<
+  typeof PendingQuestionPayloadSchema
+>;
+export type ToolApprovalGuardianPayload = z.infer<
+  typeof ToolApprovalPayloadSchema
+>;
+export type ToolGrantGuardianPayload = z.infer<typeof ToolGrantPayloadSchema>;
+export type AccessRequestGuardianPayload = z.infer<
+  typeof AccessRequestGuardianPayloadSchema
+>;
+export type GuardianQuestionPayload = z.infer<
+  typeof GuardianQuestionPayloadSchema
+>;
 
 interface GuardianQuestionModeResolution {
   mode: GuardianQuestionInstructionMode;
   requestKind: GuardianQuestionRequestKind | null;
 }
 
-function nonEmptyString(value: unknown): string | null {
-  if (typeof value !== "string") return null;
-  const trimmed = value.trim();
-  return trimmed.length > 0 ? trimmed : null;
-}
-
-function parseGuardianQuestionRequestKind(
-  payload: Record<string, unknown>,
-): GuardianQuestionRequestKind | null {
-  const raw = nonEmptyString(payload.requestKind);
-  if (!raw) return null;
-
-  switch (raw) {
-    case "pending_question":
-    case "tool_approval":
-    case "tool_grant_request":
-    case "access_request":
-      return raw;
-    default:
-      return null;
-  }
-}
-
-function parseBasePayload(
-  payload: Record<string, unknown>,
-): GuardianQuestionPayloadBase | null {
-  const requestId = nonEmptyString(payload.requestId);
-  const requestCode = nonEmptyString(payload.requestCode);
-  const questionText = nonEmptyString(payload.questionText);
-  if (!requestId || !requestCode || !questionText) return null;
-  return { requestId, requestCode, questionText };
-}
+// ── Payload parsing ────────────────────────────────────────────────────
 
 /**
- * Parse a guardian.question context payload into a strict discriminated union.
- *
- * Returns null when required fields for the declared requestKind are missing,
- * or when requestKind is absent/unknown.
+ * Parse a guardian.question context payload into a strict discriminated union
+ * using Zod validation. Returns null when the payload is missing required
+ * fields or has an unknown/missing requestKind.
  */
 export function parseGuardianQuestionPayload(
   payload: Record<string, unknown>,
 ): GuardianQuestionPayload | null {
-  const requestKind = parseGuardianQuestionRequestKind(payload);
-  if (!requestKind) return null;
-
-  const base = parseBasePayload(payload);
-  if (!base) return null;
-
-  switch (requestKind) {
-    case "pending_question": {
-      const callSessionId = nonEmptyString(payload.callSessionId);
-      const activeGuardianRequestCount =
-        typeof payload.activeGuardianRequestCount === "number"
-          ? payload.activeGuardianRequestCount
-          : undefined;
-      const toolName = nonEmptyString(payload.toolName);
-      if (
-        !callSessionId ||
-        activeGuardianRequestCount === undefined ||
-        Number.isNaN(activeGuardianRequestCount)
-      ) {
-        return null;
-      }
-      const pendingQuestionPayload: PendingQuestionGuardianPayload = {
-        requestKind,
-        ...base,
-        callSessionId,
-        activeGuardianRequestCount,
-      };
-      if (toolName) {
-        pendingQuestionPayload.toolName = toolName;
-      }
-      return {
-        ...pendingQuestionPayload,
-      };
-    }
-    case "tool_approval":
-    case "tool_grant_request": {
-      const toolName = nonEmptyString(payload.toolName);
-      if (!toolName) return null;
-      return {
-        requestKind,
-        ...base,
-        toolName,
-      };
-    }
-    case "access_request":
-      return {
-        requestKind,
-        ...base,
-      };
-    default:
-      return null;
-  }
+  const result = GuardianQuestionPayloadSchema.safeParse(payload);
+  return result.success ? result.data : null;
 }
 
 function resolveGuardianInstructionModeForRequestKind(
@@ -242,7 +227,7 @@ function resolveGuardianInstructionModeForRequestKind(
   toolName?: string | null,
 ): GuardianQuestionInstructionMode {
   const config = REQUEST_KIND_MODE_CONFIG[requestKind];
-  const normalizedToolName = nonEmptyString(toolName);
+  const normalizedToolName = nonEmpty(toolName ?? undefined) ?? null;
   if (normalizedToolName && config.modeWhenToolNamePresent) {
     return config.modeWhenToolNamePresent;
   }
@@ -257,16 +242,14 @@ export function resolveGuardianInstructionModeFromFields(
   requestKind: GuardianQuestionRequestKind;
   mode: GuardianQuestionInstructionMode;
 } | null {
-  const requestKind = parseGuardianQuestionRequestKind({
-    requestKind: requestKindValue,
-  });
-  if (!requestKind) return null;
+  const parsed = GuardianQuestionRequestKindSchema.safeParse(requestKindValue);
+  if (!parsed.success) return null;
 
   return {
-    requestKind,
+    requestKind: parsed.data,
     mode: resolveGuardianInstructionModeForRequestKind(
-      requestKind,
-      nonEmptyString(toolNameValue),
+      parsed.data,
+      typeof toolNameValue === "string" ? toolNameValue : null,
     ),
   };
 }
@@ -283,6 +266,23 @@ export function resolveGuardianInstructionModeForRequest(
   return modeResolution.mode;
 }
 
+/**
+ * Resolve instruction mode directly from a typed guardian question payload.
+ * Avoids re-parsing when the caller already holds a validated payload.
+ */
+export function resolveGuardianInstructionModeFromPayload(
+  payload: GuardianQuestionPayload,
+): GuardianQuestionModeResolution {
+  const toolName = "toolName" in payload ? payload.toolName : undefined;
+  return {
+    mode: resolveGuardianInstructionModeForRequestKind(
+      payload.requestKind,
+      toolName ?? null,
+    ),
+    requestKind: payload.requestKind,
+  };
+}
+
 function getModeTextConfig(
   mode: GuardianQuestionInstructionMode,
 ): GuardianModeTextConfig {
@@ -420,28 +420,18 @@ export function stripConflictingGuardianRequestInstructions(
 }
 
 /**
- * Resolve guardian reply instruction mode from request kind.
+ * Resolve guardian reply instruction mode from a raw context payload.
  *
- * Requires a valid requestKind in the payload. When the payload cannot be
- * fully parsed as a typed guardian question, falls back to field-level
- * requestKind resolution. If requestKind is missing or unknown, defaults
- * to "approval" mode.
+ * Attempts Zod-based parsing first. When that fails, falls back to
+ * field-level requestKind resolution. Defaults to "approval" mode
+ * when requestKind is missing or unknown.
  */
 export function resolveGuardianQuestionInstructionMode(
   payload: Record<string, unknown>,
 ): GuardianQuestionModeResolution {
   const parsed = parseGuardianQuestionPayload(payload);
   if (parsed) {
-    const parsedToolName = nonEmptyString(
-      "toolName" in parsed ? parsed.toolName : null,
-    );
-    return {
-      mode: resolveGuardianInstructionModeForRequestKind(
-        parsed.requestKind,
-        parsedToolName,
-      ),
-      requestKind: parsed.requestKind,
-    };
+    return resolveGuardianInstructionModeFromPayload(parsed);
   }
 
   const requestKindResolution = resolveGuardianInstructionModeFromFields(

package/src/notifications/home-feed-side-effect.ts

@@ -22,7 +22,7 @@ import { getConversation } from "../memory/conversation-crud.js";
 import { isBackgroundConversationType } from "../memory/conversation-types.js";
 import { getLogger } from "../util/logger.js";
 import { isConversationSeedSane } from "./conversation-seed-composer.js";
-import { readPayloadString } from "./copy-composer.js";
+import { readPayloadString } from "./notification-utils.js";
 import type { NotificationSignal } from "./signal.js";
 import type { NotificationDecision, RenderedChannelCopy } from "./types.js";
 
@@ -58,10 +58,8 @@ export async function writeHomeFeedItemForSignal(
   decision: NotificationDecision,
   fallbackConversationId?: string,
 ): Promise<FeedItem | null> {
-  const { mirror, sourceConversationId } = resolveHomeFeedMirror(
-    signal,
-    fallbackConversationId,
-  );
+  const { mirror, sourceConversationId, sourceScheduleJobId } =
+    resolveHomeFeedMirror(signal, fallbackConversationId);
   if (!mirror) return null;
 
   const renderedCopy =
@@ -106,13 +104,28 @@ export async function writeHomeFeedItemForSignal(
 
   const category = deriveCategory(signal);
   const panelKind = deriveDetailPanelKind(signal);
-  const metadata =
+
+  const baseMetadata =
     signal.contextPayload &&
     typeof signal.contextPayload === "object" &&
     !Array.isArray(signal.contextPayload)
-      ? (signal.contextPayload as Record<string, unknown>)
+      ? { ...(signal.contextPayload as Record<string, unknown>) }
       : undefined;
 
+  // Link scheduled-run notifications back to their schedule. `notify`-mode
+  // jobs put `scheduleId` directly in the context payload; `execute`-mode (and
+  // other agent-backed) jobs only tag their conversation, so fall back to the
+  // source conversation's `scheduleJobId`.
+  const scheduleId =
+    readPayloadString(signal.contextPayload, "scheduleId") ??
+    sourceScheduleJobId ??
+    undefined;
+
+  const metadata =
+    scheduleId !== undefined
+      ? { ...(baseMetadata ?? {}), scheduleId }
+      : baseMetadata;
+
   const item: FeedItem = {
     id: `notif:${signal.signalId}`,
     type: "notification",
@@ -202,8 +215,11 @@ function resolveHomeFeedMirror(
 ): {
   mirror: boolean;
   sourceConversationId?: string;
+  sourceScheduleJobId?: string;
 } {
-  let sourceRow: { conversationType?: string } | null = null;
+  let sourceRow:
+    | { conversationType?: string; scheduleJobId?: string | null }
+    | null = null;
   if (signal.sourceContextId) {
     try {
       sourceRow = getConversation(signal.sourceContextId) ?? null;
@@ -219,15 +235,16 @@ function resolveHomeFeedMirror(
   const sourceConversationId = sourceRow
     ? signal.sourceContextId
     : fallbackConversationId;
+  const sourceScheduleJobId = sourceRow?.scheduleJobId ?? undefined;
 
   if (signal.sourceChannel === "assistant_tool") {
-    return { mirror: true, sourceConversationId };
+    return { mirror: true, sourceConversationId, sourceScheduleJobId };
   }
   if (signal.attentionHints.isAsyncBackground) {
-    return { mirror: true, sourceConversationId };
+    return { mirror: true, sourceConversationId, sourceScheduleJobId };
   }
   if (isBackgroundConversationType(sourceRow?.conversationType)) {
-    return { mirror: true, sourceConversationId };
+    return { mirror: true, sourceConversationId, sourceScheduleJobId };
   }
   return { mirror: false };
 }

package/src/notifications/notification-utils.ts

@@ -0,0 +1,66 @@
+/**
+ * Shared leaf utilities for the notification pipeline.
+ *
+ * This module has no intra-pipeline imports — it depends only on Node
+ * stdlib — so any notification module can import it without creating
+ * circular dependencies.
+ */
+
+// ── String helpers ──────────────────────────────────────────────────────────
+
+/** Return `value` trimmed, or `undefined` when blank/nullish. */
+export function nonEmpty(value: string | null | undefined): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+/**
+ * Safely read a string property from an unknown-typed payload object.
+ * Returns `undefined` when the payload is falsy, not an object, or the
+ * key does not hold a string value.
+ */
+export function readPayloadString(
+  payload: unknown,
+  key: string,
+): string | undefined {
+  if (!payload || typeof payload !== "object") return undefined;
+  const value = (payload as Record<string, unknown>)[key];
+  return typeof value === "string" ? value : undefined;
+}
+
+// ── Sanitization ────────────────────────────────────────────────────────────
+
+const IDENTITY_FIELD_MAX_LENGTH = 120;
+
+/**
+ * Sanitize an untrusted identity field for inclusion in notification copy.
+ *
+ * - Strips control characters (U+0000–U+001F, U+007F–U+009F) and newlines.
+ * - Clamps to 120 characters.
+ */
+export function sanitizeIdentityField(value: string): string {
+  const stripped = value.replace(/[\x00-\x1f\x7f-\x9f\r\n]+/g, " ").trim();
+  const clamped =
+    stripped.length > IDENTITY_FIELD_MAX_LENGTH
+      ? stripped.slice(0, IDENTITY_FIELD_MAX_LENGTH) + "…"
+      : stripped;
+  return clamped;
+}
+
+export const MESSAGE_PREVIEW_MAX_LENGTH = 200;
+
+/**
+ * Sanitize an untrusted message preview for inclusion in notification copy.
+ *
+ * Same as {@link sanitizeIdentityField} but uses a higher length limit
+ * (200 chars) suited for message previews.
+ */
+export function sanitizeMessagePreview(value: string): string {
+  const stripped = value.replace(/[\x00-\x1f\x7f-\x9f\r\n]+/g, " ").trim();
+  const clamped =
+    stripped.length > MESSAGE_PREVIEW_MAX_LENGTH
+      ? stripped.slice(0, MESSAGE_PREVIEW_MAX_LENGTH) + "…"
+      : stripped;
+  return clamped;
+}

package/src/notifications/signal.ts

@@ -159,6 +159,12 @@ export interface AccessRequestContextPayload {
   previousMemberStatus: string | null;
   /** Preview of the requester's original message (first ~200 chars). */
   messagePreview: string | null;
+  /** Slack-specific: user is from an external workspace (Slack Connect). */
+  isStranger?: boolean;
+  /** Slack-specific: user is a guest / restricted account. */
+  isRestricted?: boolean;
+  /** Slack message timestamp (e.g. "1234567890.123456") for permalink construction. */
+  messageTs?: string;
 }
 
 export interface GuardianChannelActivationPayload {

package/src/notifications/tool-approval-copy.ts

@@ -0,0 +1,142 @@
+/**
+ * Deterministic helpers for building guardian-facing tool-approval copy.
+ *
+ * Produces Surface card seed content blocks for `tool_approval`,
+ * `tool_grant_request`, and voice/call `pending_question` (with `toolName`)
+ * guardian questions, enabling Approve/Reject buttons in the Vellum in-app
+ * channel (web/macOS/iOS).
+ */
+
+import { buildApprovalCardBlocks } from "./approval-card-builder.js";
+import {
+  buildGuardianRequestCodeInstruction,
+  type GuardianQuestionPayload,
+  type LenientToolApprovalPayload,
+  LenientToolApprovalPayloadSchema,
+  parseGuardianQuestionPayload,
+  resolveGuardianInstructionModeFromFields,
+  resolveGuardianInstructionModeFromPayload,
+} from "./guardian-question-mode.js";
+import { nonEmpty, sanitizeIdentityField } from "./notification-utils.js";
+
+// ── Approval detection ──────────────────────────────────────────────────────
+
+/**
+ * Determine whether a typed guardian.question payload represents a tool
+ * approval (as opposed to a free-text answer). Uses the canonical mode
+ * resolver in `guardian-question-mode.ts` — the single source of truth
+ * for the requestKind → instructionMode mapping.
+ */
+function isToolApprovalPayload(payload: GuardianQuestionPayload): boolean {
+  const { mode } = resolveGuardianInstructionModeFromPayload(payload);
+  return mode === "approval" && payload.requestKind !== "access_request";
+}
+
+/**
+ * Lenient approval detection for partially-constructed payloads that don't
+ * satisfy the strict discriminated union schema.
+ */
+function isLenientToolApproval(payload: LenientToolApprovalPayload): boolean {
+  const modeResolution = resolveGuardianInstructionModeFromFields(
+    payload.requestKind,
+    payload.toolName,
+  );
+  if (!modeResolution) return false;
+  return (
+    modeResolution.mode === "approval" &&
+    payload.requestKind !== "access_request"
+  );
+}
+
+// ── Seed content blocks (Surface-based rendering) ───────────────────────────
+
+/**
+ * Build structured content blocks for a tool approval/grant notification seed
+ * message. Returns `null` when the payload does not represent a tool approval.
+ *
+ * Accepts both strict `GuardianQuestionPayload` (Zod-validated) and raw
+ * `Record<string, unknown>` payloads. For raw payloads, attempts strict
+ * parsing first, then falls back to lenient field extraction so cards
+ * still render when optional fields are absent.
+ */
+export function buildToolApprovalSeedContentBlocks(
+  payload: GuardianQuestionPayload,
+): unknown[] | null;
+export function buildToolApprovalSeedContentBlocks(
+  payload: Record<string, unknown>,
+): unknown[] | null;
+export function buildToolApprovalSeedContentBlocks(
+  payload: GuardianQuestionPayload | Record<string, unknown>,
+): unknown[] | null {
+  // Try strict Zod parsing first (full discriminated union).
+  const strict = parseGuardianQuestionPayload(
+    payload as Record<string, unknown>,
+  );
+  if (strict) {
+    if (!isToolApprovalPayload(strict)) return null;
+    return buildCardFromFields(strict);
+  }
+
+  // Fall back to lenient parsing — requires only `requestKind`.
+  const lenient = LenientToolApprovalPayloadSchema.safeParse(payload);
+  if (!lenient.success) return null;
+  if (!isLenientToolApproval(lenient.data)) return null;
+  return buildCardFromFields(lenient.data);
+}
+
+// ── Card construction (shared between strict and lenient paths) ─────────────
+
+function buildCardFromFields(
+  p: GuardianQuestionPayload | LenientToolApprovalPayload,
+): unknown[] {
+  const toolName =
+    ("toolName" in p ? nonEmpty(p.toolName) : undefined) ?? "unknown tool";
+  const rawRequester = nonEmpty(p.requesterIdentifier);
+  const requester = rawRequester
+    ? sanitizeIdentityField(rawRequester)
+    : "Someone";
+
+  const isGrant = p.requestKind === "tool_grant_request";
+
+  const metadata: Array<{ label: string; value: string }> = [];
+  metadata.push({ label: "Tool", value: toolName });
+  const sourceChannel = nonEmpty(p.sourceChannel);
+  if (sourceChannel) {
+    metadata.push({ label: "Source", value: sourceChannel });
+  }
+
+  const body = p.questionText
+    ? `> ${p.questionText}`
+    : "No additional context available.";
+
+  // Fallback text with request-code instructions for older clients.
+  const baseFallback =
+    p.questionText ?? `${requester} is requesting approval to use ${toolName}`;
+  let fallbackText = baseFallback;
+  const requestCode = nonEmpty(p.requestCode);
+  if (requestCode) {
+    const modeResolution = resolveGuardianInstructionModeFromFields(
+      p.requestKind,
+      "toolName" in p ? (p.toolName ?? undefined) : undefined,
+    );
+    const mode = modeResolution?.mode ?? "approval";
+    const instruction = buildGuardianRequestCodeInstruction(
+      requestCode.trim().toUpperCase(),
+      mode,
+    );
+    fallbackText = `${baseFallback}\n\n${instruction}`;
+  }
+
+  return buildApprovalCardBlocks({
+    surfaceIdPrefix: "tool-approval",
+    cardTitle: isGrant ? "Tool Grant Request" : "Tool Approval",
+    requesterName: requester,
+    subtitle: isGrant
+      ? "Requesting permission to use this tool"
+      : "Requesting approval to run this tool",
+    body,
+    metadata,
+    requestId: nonEmpty(p.requestId),
+    fallbackText,
+  });
+}