@vellumai/assistant 0.3.3 → 0.3.5

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

@@ -44,6 +44,8 @@ import type {
   MessageProcessor,
   RuntimeAttachmentMetadata,
 } from '../http-types.js';
+import type { GuardianRuntimeContext } from '../../daemon/session-runtime-assembly.js';
+import { composeApprovalMessage } from '../approval-message-composer.js';
 
 const log = getLogger('runtime-http');
 
@@ -110,6 +112,19 @@ export interface GuardianContext {
   denialReason?: DenialReason;
 }
 
+function toGuardianRuntimeContext(sourceChannel: string, ctx: GuardianContext): GuardianRuntimeContext {
+  return {
+    sourceChannel,
+    actorRole: ctx.actorRole,
+    guardianChatId: ctx.guardianChatId,
+    guardianExternalUserId: ctx.guardianExternalUserId,
+    requesterIdentifier: ctx.requesterIdentifier,
+    requesterExternalUserId: ctx.requesterExternalUserId,
+    requesterChatId: ctx.requesterChatId,
+    denialReason: ctx.denialReason,
+  };
+}
+
 /** Guardian approval request expiry (30 minutes). */
 const GUARDIAN_APPROVAL_TTL_MS = 30 * 60 * 1000;
 
@@ -127,12 +142,21 @@ function effectivePromptText(
   return plainTextFallback;
 }
 
-// ---------------------------------------------------------------------------
-// Feature flag
-// ---------------------------------------------------------------------------
+/**
+ * Build contextual deny guidance for guardian-gated auto-deny paths.
+ * This is passed through the confirmation pipeline so the assistant can
+ * produce a single, user-facing message with next steps.
+ */
+function buildGuardianDenyContext(
+  toolName: string,
+  denialReason: DenialReason,
+  sourceChannel: string,
+): string {
+  if (denialReason === 'no_identity') {
+    return `Permission denied: ${composeApprovalMessage({ scenario: 'guardian_deny_no_identity', toolName, channel: sourceChannel })} Do not retry yet. Ask the user to message from a verifiable direct account/chat, and then retry after identity is available.`;
+  }
 
-export function isChannelApprovalsEnabled(): boolean {
-  return process.env.CHANNEL_APPROVALS_ENABLED === 'true';
+  return `Permission denied: ${composeApprovalMessage({ scenario: 'guardian_deny_no_binding', toolName, channel: sourceChannel })} Do not retry yet. Offer to set up guardian verification. The setup flow will provide a verification token to send as /guardian_verify <token>.`;
 }
 
 // ---------------------------------------------------------------------------
@@ -169,13 +193,22 @@ export async function handleDeleteConversation(req: Request, assistantId: string
     return Response.json({ error: 'externalChatId is required' }, { status: 400 });
   }
 
-  // Delete both legacy and scoped conversation key aliases to handle
-  // migration scenarios where either or both keys may exist.
+  // Delete the assistant-scoped key unconditionally. The legacy key is
+  // canonical for the self assistant and must not be deleted from non-self
+  // routes, otherwise a non-self reset can accidentally reset self state.
   const legacyKey = `${sourceChannel}:${externalChatId}`;
   const scopedKey = `asst:${assistantId}:${sourceChannel}:${externalChatId}`;
-  deleteConversationKey(legacyKey);
   deleteConversationKey(scopedKey);
-  externalConversationStore.deleteBindingByChannelChat(sourceChannel, externalChatId);
+  if (assistantId === 'self') {
+    deleteConversationKey(legacyKey);
+  }
+  // external_conversation_bindings is currently assistant-agnostic
+  // (unique by sourceChannel + externalChatId). Restrict mutations to the
+  // canonical self-assistant route so multi-assistant legacy routes do not
+  // clobber each other's bindings.
+  if (assistantId === 'self') {
+    externalConversationStore.deleteBindingByChannelChat(sourceChannel, externalChatId);
+  }
 
   return Response.json({ ok: true });
 }
@@ -338,15 +371,19 @@ export async function handleChannelInbound(
     { sourceMessageId, assistantId },
   );
 
-  // Upsert external conversation binding with sender metadata
-  externalConversationStore.upsertBinding({
-    conversationId: result.conversationId,
-    sourceChannel,
-    externalChatId,
-    externalUserId: body.senderExternalUserId ?? null,
-    displayName: body.senderName ?? null,
-    username: body.senderUsername ?? null,
-  });
+  // external_conversation_bindings is assistant-agnostic. Restrict writes to
+  // self so assistant-scoped legacy routes do not overwrite each other's
+  // channel binding metadata for the same chat.
+  if (assistantId === 'self') {
+    externalConversationStore.upsertBinding({
+      conversationId: result.conversationId,
+      sourceChannel,
+      externalChatId,
+      externalUserId: body.senderExternalUserId ?? null,
+      displayName: body.senderName ?? null,
+      username: body.senderUsername ?? null,
+    });
+  }
 
   const metadataHintsRaw = sourceMetadata?.hints;
   const metadataHints = Array.isArray(metadataHintsRaw)
@@ -374,16 +411,19 @@ export async function handleChannelInbound(
         token,
         body.senderExternalUserId,
         externalChatId,
+        body.senderUsername,
+        body.senderName,
       );
 
       const replyText = verifyResult.success
-        ? 'Guardian verified successfully. Your identity is now linked to this bot.'
-        : 'Verification failed. Please try again later.';
+        ? composeApprovalMessage({ scenario: 'guardian_verify_success' })
+        : verifyResult.reason;
 
       try {
         await deliverChannelReply(replyCallbackUrl, {
           chatId: externalChatId,
           text: replyText,
+          assistantId,
         }, bearerToken);
       } catch (err) {
         log.error({ err, externalChatId }, 'Failed to deliver guardian verification reply');
@@ -403,18 +443,26 @@ export async function handleChannelInbound(
   // When a guardian binding exists, non-guardian actors get stricter
   // side-effect controls and their approvals route to the guardian's chat.
   //
-  // Guardian enforcement runs independently of CHANNEL_APPROVALS_ENABLED.
-  // The approval flag only gates the interactive approval prompting UX;
-  // actor-role resolution and fail-closed denial are always active.
-  let guardianCtx: GuardianContext = { actorRole: 'guardian' };
+  // Guardian actor-role resolution always runs.
+  let guardianCtx: GuardianContext;
   if (body.senderExternalUserId) {
+    const requesterLabel = body.senderUsername
+      ? `@${body.senderUsername}`
+      : body.senderExternalUserId;
     const senderIsGuardian = isGuardian(assistantId, sourceChannel, body.senderExternalUserId);
-    if (!senderIsGuardian) {
+    if (senderIsGuardian) {
+      const binding = getGuardianBinding(assistantId, sourceChannel);
+      guardianCtx = {
+        actorRole: 'guardian',
+        guardianChatId: binding?.guardianDeliveryChatId ?? externalChatId,
+        guardianExternalUserId: binding?.guardianExternalUserId ?? body.senderExternalUserId,
+        requesterIdentifier: requesterLabel,
+        requesterExternalUserId: body.senderExternalUserId,
+        requesterChatId: externalChatId,
+      };
+    } else {
       const binding = getGuardianBinding(assistantId, sourceChannel);
       if (binding) {
-        const requesterLabel = body.senderUsername
-          ? `@${body.senderUsername}`
-          : body.senderExternalUserId;
         guardianCtx = {
           actorRole: 'non-guardian',
           guardianChatId: binding.guardianDeliveryChatId,
@@ -429,29 +477,28 @@ export async function handleChannelInbound(
         guardianCtx = {
           actorRole: 'unverified_channel',
           denialReason: 'no_binding',
+          requesterIdentifier: requesterLabel,
           requesterExternalUserId: body.senderExternalUserId,
           requesterChatId: externalChatId,
         };
       }
     }
   } else {
-    // No sender identity available — fail-closed when guardian enforcement
-    // is active for this channel. If a binding exists, unknown actors must
-    // not be granted default guardian permissions.
-    const binding = getGuardianBinding(assistantId, sourceChannel);
-    if (binding) {
-      guardianCtx = {
-        actorRole: 'unverified_channel',
-        denialReason: 'no_identity',
-        requesterExternalUserId: undefined,
-        requesterChatId: externalChatId,
-      };
-    }
+    // No sender identity available — treat as unverified and fail closed.
+    // Multi-actor channels must not grant default guardian permissions when
+    // the inbound actor cannot be identified.
+    guardianCtx = {
+      actorRole: 'unverified_channel',
+      denialReason: 'no_identity',
+      requesterIdentifier: body.senderUsername ? `@${body.senderUsername}` : undefined,
+      requesterExternalUserId: undefined,
+      requesterChatId: externalChatId,
+    };
   }
 
-  // ── Approval interception (gated behind feature flag) ──
+  // ── Approval interception ──
+  // Keep this active whenever orchestrator + callback context are available.
   if (
-    isChannelApprovalsEnabled() &&
     runOrchestrator &&
     replyCallbackUrl &&
     !result.duplicate
@@ -506,7 +553,9 @@ export async function handleChannelInbound(
       senderName: body.senderName,
       senderExternalUserId: body.senderExternalUserId,
       senderUsername: body.senderUsername,
+      guardianCtx,
       replyCallbackUrl,
+      assistantId,
     });
 
     const contentToCheck = content ?? '';
@@ -522,13 +571,15 @@ export async function handleChannelInbound(
       throw new IngressBlockedError(ingressCheck.userNotice!, ingressCheck.detectedTypes);
     }
 
-    // When approval flow is enabled and we have an orchestrator, use the
-    // orchestrator-backed path which properly intercepts confirmation_request
-    // events and sends proactive approval prompts to the channel.
-    const useApprovalPath =
-      isChannelApprovalsEnabled() && runOrchestrator && replyCallbackUrl;
+    // Use the approval-aware orchestrator path whenever orchestration and a
+    // callback delivery target are available. This keeps approval handling
+    // consistent across all channels and avoids silent prompt timeouts.
+    const useApprovalPath = Boolean(
+      runOrchestrator &&
+      replyCallbackUrl,
+    );
 
-    if (useApprovalPath) {
+    if (useApprovalPath && runOrchestrator && replyCallbackUrl) {
       processChannelMessageWithApprovals({
         orchestrator: runOrchestrator,
         conversationId: result.conversationId,
@@ -541,6 +592,8 @@ export async function handleChannelInbound(
         bearerToken,
         guardianCtx,
         assistantId,
+        metadataHints,
+        metadataUxBrief,
       });
     } else {
       // Fire-and-forget: process the message and deliver the reply in the background.
@@ -553,10 +606,12 @@ export async function handleChannelInbound(
         attachmentIds: hasAttachments ? attachmentIds : undefined,
         sourceChannel,
         externalChatId,
+        guardianCtx,
         metadataHints,
         metadataUxBrief,
         replyCallbackUrl,
         bearerToken,
+        assistantId,
       });
     }
   }
@@ -576,10 +631,12 @@ interface BackgroundProcessingParams {
   attachmentIds?: string[];
   sourceChannel: string;
   externalChatId: string;
+  guardianCtx: GuardianContext;
   metadataHints: string[];
   metadataUxBrief?: string;
   replyCallbackUrl?: string;
   bearerToken?: string;
+  assistantId?: string;
 }
 
 function processChannelMessageInBackground(params: BackgroundProcessingParams): void {
@@ -591,10 +648,12 @@ function processChannelMessageInBackground(params: BackgroundProcessingParams):
     attachmentIds,
     sourceChannel,
     externalChatId,
+    guardianCtx,
     metadataHints,
     metadataUxBrief,
     replyCallbackUrl,
     bearerToken,
+    assistantId,
   } = params;
 
   (async () => {
@@ -609,6 +668,8 @@ function processChannelMessageInBackground(params: BackgroundProcessingParams):
             hints: metadataHints.length > 0 ? metadataHints : undefined,
             uxBrief: metadataUxBrief,
           },
+          assistantId,
+          guardianContext: toGuardianRuntimeContext(sourceChannel, guardianCtx),
         },
         sourceChannel,
       );
@@ -616,7 +677,13 @@ function processChannelMessageInBackground(params: BackgroundProcessingParams):
       channelDeliveryStore.markProcessed(eventId);
 
       if (replyCallbackUrl) {
-        await deliverReplyViaCallback(conversationId, externalChatId, replyCallbackUrl, bearerToken);
+        await deliverReplyViaCallback(
+          conversationId,
+          externalChatId,
+          replyCallbackUrl,
+          bearerToken,
+          assistantId,
+        );
       }
     } catch (err) {
       log.error({ err, conversationId }, 'Background channel message processing failed');
@@ -665,6 +732,8 @@ interface ApprovalProcessingParams {
   bearerToken?: string;
   guardianCtx: GuardianContext;
   assistantId: string;
+  metadataHints: string[];
+  metadataUxBrief?: string;
 }
 
 /**
@@ -692,6 +761,8 @@ function processChannelMessageWithApprovals(params: ApprovalProcessingParams): v
     bearerToken,
     guardianCtx,
     assistantId,
+    metadataHints,
+    metadataUxBrief,
   } = params;
 
   const isNonGuardian = guardianCtx.actorRole === 'non-guardian';
@@ -706,6 +777,10 @@ function processChannelMessageWithApprovals(params: ApprovalProcessingParams): v
         {
           ...((isNonGuardian || isUnverifiedChannel) ? { forceStrictSideEffects: true } : {}),
           sourceChannel,
+          hints: metadataHints.length > 0 ? metadataHints : undefined,
+          uxBrief: metadataUxBrief,
+          assistantId,
+          guardianContext: toGuardianRuntimeContext(sourceChannel, guardianCtx),
         },
       );
 
@@ -714,6 +789,14 @@ function processChannelMessageWithApprovals(params: ApprovalProcessingParams): v
       const startTime = Date.now();
       const pollMaxWait = getEffectivePollMaxWait();
       let lastStatus = run.status;
+      // Track whether a post-decision delivery path is guaranteed for this
+      // run. Set to true only when the approval prompt is successfully
+      // delivered (guardian or standard path), meaning
+      // handleApprovalInterception will schedule schedulePostDecisionDelivery
+      // when a decision arrives. Auto-deny paths (unverified channel, prompt
+      // delivery failures) do NOT set this flag because no post-decision
+      // delivery is scheduled in those cases.
+      let hasPostDecisionDelivery = false;
 
       while (Date.now() - startTime < pollMaxWait) {
         await new Promise((resolve) => setTimeout(resolve, RUN_POLL_INTERVAL_MS));
@@ -726,18 +809,16 @@ function processChannelMessageWithApprovals(params: ApprovalProcessingParams): v
 
           if (isUnverifiedChannel && pending.length > 0) {
             // Unverified channel — auto-deny the sensitive action (fail-closed).
-            handleChannelDecision(conversationId, { action: 'reject', source: 'plain_text' }, orchestrator);
-            const denialText = guardianCtx.denialReason === 'no_identity'
-              ? `The action "${pending[0].toolName}" requires guardian approval, but your identity could not be determined. The action has been denied. Please ensure your messaging client sends user identity information.`
-              : `The action "${pending[0].toolName}" requires guardian approval, but no guardian has been set up for this channel. The action has been denied. Please ask an administrator to configure a guardian.`;
-            try {
-              await deliverChannelReply(replyCallbackUrl, {
-                chatId: externalChatId,
-                text: denialText,
-              }, bearerToken);
-            } catch (err) {
-              log.error({ err, runId: run.id }, 'Failed to deliver unverified-channel denial notice');
-            }
+            handleChannelDecision(
+              conversationId,
+              { action: 'reject', source: 'plain_text' },
+              orchestrator,
+              buildGuardianDenyContext(
+                pending[0].toolName,
+                guardianCtx.denialReason ?? 'no_binding',
+                sourceChannel,
+              ),
+            );
           } else if (isNonGuardian && guardianCtx.guardianChatId && pending.length > 0) {
             // Non-guardian actor: route the approval prompt to the guardian's chat
             const guardianPrompt = buildGuardianApprovalPrompt(
@@ -774,9 +855,11 @@ function processChannelMessageWithApprovals(params: ApprovalProcessingParams): v
                 guardianCtx.guardianChatId,
                 guardianText,
                 uiMetadata,
+                assistantId,
                 bearerToken,
               );
               guardianNotified = true;
+              hasPostDecisionDelivery = true;
             } catch (err) {
               log.error({ err, runId: run.id }, 'Failed to deliver guardian approval prompt');
               // Deny the approval and the underlying run — fail-closed. If
@@ -788,7 +871,8 @@ function processChannelMessageWithApprovals(params: ApprovalProcessingParams): v
               try {
                 await deliverChannelReply(replyCallbackUrl, {
                   chatId: guardianCtx.requesterChatId ?? externalChatId,
-                  text: `Your request to run "${pending[0].toolName}" could not be sent to the guardian for approval. The action has been denied.`,
+                  text: composeApprovalMessage({ scenario: 'guardian_delivery_failed', toolName: pending[0].toolName }),
+                  assistantId,
                 }, bearerToken);
               } catch (notifyErr) {
                 log.error({ err: notifyErr, runId: run.id }, 'Failed to notify requester of guardian delivery failure');
@@ -800,7 +884,8 @@ function processChannelMessageWithApprovals(params: ApprovalProcessingParams): v
               try {
                 await deliverChannelReply(replyCallbackUrl, {
                   chatId: guardianCtx.requesterChatId ?? externalChatId,
-                  text: `Your request to run "${pending[0].toolName}" has been sent to the guardian for approval.`,
+                  text: composeApprovalMessage({ scenario: 'guardian_request_forwarded', toolName: pending[0].toolName }),
+                  assistantId,
                 }, bearerToken);
               } catch (err) {
                 log.error({ err, runId: run.id }, 'Failed to notify requester of pending guardian approval');
@@ -823,8 +908,10 @@ function processChannelMessageWithApprovals(params: ApprovalProcessingParams): v
                   externalChatId,
                   promptTextForChannel,
                   uiMetadata,
+                  assistantId,
                   bearerToken,
                 );
+                hasPostDecisionDelivery = true;
               } catch (err) {
                 // Fail-closed: if we cannot deliver the approval prompt, the
                 // user will never see it and the run would hang indefinitely
@@ -867,7 +954,13 @@ function processChannelMessageWithApprovals(params: ApprovalProcessingParams): v
         // rather than permanently losing the reply.
         if (channelDeliveryStore.claimRunDelivery(run.id)) {
           try {
-            await deliverReplyViaCallback(conversationId, externalChatId, replyCallbackUrl, bearerToken);
+            await deliverReplyViaCallback(
+              conversationId,
+              externalChatId,
+              replyCallbackUrl,
+              bearerToken,
+              assistantId,
+            );
           } catch (deliveryErr) {
             channelDeliveryStore.resetRunDeliveryClaim(run.id);
             throw deliveryErr;
@@ -884,23 +977,39 @@ function processChannelMessageWithApprovals(params: ApprovalProcessingParams): v
             updateApprovalDecision(approvalReq.id, { status: outcomeStatus });
           }
         }
-      } else if (finalRun?.status === 'needs_confirmation') {
-        // The run is waiting for an approval decision but the poll window has
-        // elapsed. Mark the event as processed rather than failed — the run
-        // will resume when the user clicks approve/reject, and
-        // `handleApprovalInterception` will deliver the reply via its own
-        // post-decision poll. Marking it failed would cause the generic retry
-        // sweep to replay through `processMessage`, which throws "Session is
+      } else if (
+        finalRun?.status === 'needs_confirmation' ||
+        (hasPostDecisionDelivery && finalRun?.status === 'running')
+      ) {
+        // The run is either still waiting for an approval decision or was
+        // recently approved and has resumed execution. In both cases, mark
+        // the event as processed rather than failed:
+        //
+        // - needs_confirmation: the run will resume when the user clicks
+        //   approve/reject, and `handleApprovalInterception` will deliver
+        //   the reply via `schedulePostDecisionDelivery`.
+        //
+        // - running (after successful prompt delivery): an approval was
+        //   applied near the poll deadline and the run resumed but hasn't
+        //   reached terminal state yet. `handleApprovalInterception` has
+        //   already scheduled post-decision delivery, so the final reply
+        //   will be delivered. This condition is only true when the approval
+        //   prompt was actually delivered (not in auto-deny paths), ensuring
+        //   we don't suppress retry/dead-letter for cases where no
+        //   post-decision delivery path exists.
+        //
+        // Marking either state as failed would cause the generic retry sweep
+        // to replay through `processMessage`, which throws "Session is
         // already processing a message" and dead-letters a valid conversation.
         log.warn(
-          { runId: run.id, status: finalRun.status, conversationId },
-          'Approval-path poll loop timed out while run awaits approval decision; marking event as processed',
+          { runId: run.id, status: finalRun.status, conversationId, hasPostDecisionDelivery },
+          'Approval-path poll loop timed out while run is in approval-related state; marking event as processed',
         );
         channelDeliveryStore.markProcessed(eventId);
       } else {
-        // The run is in a non-terminal, non-approval state (e.g. running,
-        // needs_secret, or disappeared). Record a processing failure so the
-        // retry/dead-letter machinery can handle it.
+        // The run is in a non-terminal, non-approval state (e.g. running
+        // without prior approval, needs_secret, or disappeared). Record a
+        // processing failure so the retry/dead-letter machinery can handle it.
         const timeoutErr = new Error(
           `Approval poll timeout: run did not reach terminal state within ${pollMaxWait}ms (status: ${finalRun?.status ?? 'null'})`,
         );
@@ -1002,7 +1111,8 @@ async function handleApprovalInterception(
         try {
           await deliverChannelReply(replyCallbackUrl, {
             chatId: externalChatId,
-            text: `You have ${allPending.length} pending approval requests. Please use the approval buttons to respond to a specific request.`,
+            text: composeApprovalMessage({ scenario: 'guardian_disambiguation', pendingCount: allPending.length }),
+            assistantId,
           }, bearerToken);
         } catch (err) {
           log.error({ err, externalChatId }, 'Failed to deliver disambiguation notice');
@@ -1034,7 +1144,8 @@ async function handleApprovalInterception(
         try {
           await deliverChannelReply(replyCallbackUrl, {
             chatId: externalChatId,
-            text: 'Only the verified guardian can approve or deny this request.',
+            text: composeApprovalMessage({ scenario: 'guardian_identity_mismatch' }),
+            assistantId,
           }, bearerToken);
         } catch (err) {
           log.error({ err, externalChatId }, 'Failed to deliver guardian identity rejection notice');
@@ -1067,14 +1178,16 @@ async function handleApprovalInterception(
 
         if (result.applied) {
           // Notify the requester's chat about the outcome with the tool name
-          const toolLabel = guardianApproval.toolName;
-          const outcomeText = decision.action === 'reject'
-            ? `Your request to run "${toolLabel}" was denied by the guardian.`
-            : `Your request to run "${toolLabel}" was approved by the guardian.`;
+          const outcomeText = composeApprovalMessage({
+            scenario: 'guardian_decision_outcome',
+            decision: decision.action === 'reject' ? 'denied' : 'approved',
+            toolName: guardianApproval.toolName,
+          });
           try {
             await deliverChannelReply(replyCallbackUrl, {
               chatId: guardianApproval.requesterChatId,
               text: outcomeText,
+              assistantId,
             }, bearerToken);
           } catch (err) {
             log.error({ err, conversationId: guardianApproval.conversationId }, 'Failed to notify requester of guardian decision');
@@ -1090,6 +1203,7 @@ async function handleApprovalInterception(
               guardianApproval.requesterChatId,
               replyCallbackUrl,
               bearerToken,
+              assistantId,
             );
           }
         }
@@ -1117,6 +1231,7 @@ async function handleApprovalInterception(
             externalChatId,
             reminderText,
             uiMetadata,
+            assistantId,
             bearerToken,
           );
         } catch (err) {
@@ -1126,11 +1241,6 @@ async function handleApprovalInterception(
 
       return { handled: true, type: 'reminder_sent' };
     }
-
-    // Callback with a run ID that no longer has a pending approval — stale button
-    if (decision?.runId) {
-      return { handled: true, type: 'stale_ignored' };
-    }
   }
 
   // ── Standard approval interception (existing flow) ──
@@ -1142,17 +1252,26 @@ async function handleApprovalInterception(
   if (guardianCtx.actorRole === 'unverified_channel') {
     const pending = getPendingConfirmationsByConversation(conversationId);
     if (pending.length > 0) {
-      handleChannelDecision(conversationId, { action: 'reject', source: 'plain_text' }, orchestrator);
-      const denialText = guardianCtx.denialReason === 'no_identity'
-        ? `The action "${pending[0].toolName}" requires guardian approval, but your identity could not be determined. The action has been denied.`
-        : `The action "${pending[0].toolName}" requires guardian approval, but no guardian has been set up for this channel. The action has been denied.`;
-      try {
-        await deliverChannelReply(replyCallbackUrl, {
-          chatId: externalChatId,
-          text: denialText,
-        }, bearerToken);
-      } catch (err) {
-        log.error({ err, conversationId }, 'Failed to deliver unverified-channel denial notice during interception');
+      const denyResult = handleChannelDecision(
+        conversationId,
+        { action: 'reject', source: 'plain_text' },
+        orchestrator,
+        buildGuardianDenyContext(
+          pending[0].toolName,
+          guardianCtx.denialReason ?? 'no_binding',
+          sourceChannel,
+        ),
+      );
+      if (denyResult.applied && denyResult.runId) {
+        schedulePostDecisionDelivery(
+          orchestrator,
+          denyResult.runId,
+          conversationId,
+          externalChatId,
+          replyCallbackUrl,
+          bearerToken,
+          assistantId,
+        );
       }
       return { handled: true, type: 'decision_applied' };
     }
@@ -1169,7 +1288,8 @@ async function handleApprovalInterception(
         try {
           await deliverChannelReply(replyCallbackUrl, {
             chatId: externalChatId,
-            text: 'Your request is pending guardian approval. Only the verified guardian can approve or deny this request.',
+            text: composeApprovalMessage({ scenario: 'request_pending_guardian' }),
+            assistantId,
           }, bearerToken);
         } catch (err) {
           log.error({ err, conversationId }, 'Failed to deliver guardian-pending notice to requester');
@@ -1195,7 +1315,8 @@ async function handleApprovalInterception(
         try {
           await deliverChannelReply(replyCallbackUrl, {
             chatId: externalChatId,
-            text: 'Your guardian approval request has expired and the action has been denied. Please try again.',
+            text: composeApprovalMessage({ scenario: 'guardian_expired_requester', toolName: pending[0].toolName }),
+            assistantId,
           }, bearerToken);
         } catch (err) {
           log.error({ err, conversationId }, 'Failed to deliver guardian-expiry notice to requester');
@@ -1247,6 +1368,7 @@ async function handleApprovalInterception(
         externalChatId,
         replyCallbackUrl,
         bearerToken,
+        assistantId,
       );
     }
 
@@ -1269,6 +1391,7 @@ async function handleApprovalInterception(
         externalChatId,
         reminderText,
         uiMetadata,
+        assistantId,
         bearerToken,
       );
     } catch (err) {
@@ -1296,6 +1419,7 @@ function schedulePostDecisionDelivery(
   externalChatId: string,
   replyCallbackUrl: string,
   bearerToken?: string,
+  assistantId?: string,
 ): void {
   (async () => {
     try {
@@ -1307,7 +1431,13 @@ function schedulePostDecisionDelivery(
         if (current.status === 'completed' || current.status === 'failed') {
           if (channelDeliveryStore.claimRunDelivery(runId)) {
             try {
-              await deliverReplyViaCallback(conversationId, externalChatId, replyCallbackUrl, bearerToken);
+              await deliverReplyViaCallback(
+                conversationId,
+                externalChatId,
+                replyCallbackUrl,
+                bearerToken,
+                assistantId,
+              );
             } catch (deliveryErr) {
               channelDeliveryStore.resetRunDeliveryClaim(runId);
               throw deliveryErr;
@@ -1331,6 +1461,7 @@ async function deliverReplyViaCallback(
   externalChatId: string,
   callbackUrl: string,
   bearerToken?: string,
+  assistantId?: string,
 ): Promise<void> {
   const msgs = conversationStore.getMessages(conversationId);
   for (let i = msgs.length - 1; i >= 0; i--) {
@@ -1353,6 +1484,7 @@ async function deliverReplyViaCallback(
           chatId: externalChatId,
           text: rendered.text || undefined,
           attachments: replyAttachments.length > 0 ? replyAttachments : undefined,
+          assistantId,
         }, bearerToken);
       }
       break;
@@ -1452,7 +1584,8 @@ export function sweepExpiredGuardianApprovals(
     // Notify the requester that the approval expired
     deliverChannelReply(deliverUrl, {
       chatId: approval.requesterChatId,
-      text: `Your guardian approval request for "${approval.toolName}" has expired and the action has been denied. Please try again.`,
+      text: composeApprovalMessage({ scenario: 'guardian_expired_requester', toolName: approval.toolName }),
+      assistantId: approval.assistantId,
     }, bearerToken).catch((err) => {
       log.error({ err, runId: approval.runId }, 'Failed to notify requester of guardian approval expiry');
     });
@@ -1460,7 +1593,8 @@ export function sweepExpiredGuardianApprovals(
     // Notify the guardian that the approval expired
     deliverChannelReply(deliverUrl, {
       chatId: approval.guardianChatId,
-      text: `The approval request for "${approval.toolName}" from user ${approval.requesterExternalUserId} has expired and was automatically denied.`,
+      text: composeApprovalMessage({ scenario: 'guardian_expired_guardian', toolName: approval.toolName, requesterIdentifier: approval.requesterExternalUserId }),
+      assistantId: approval.assistantId,
     }, bearerToken).catch((err) => {
       log.error({ err, runId: approval.runId }, 'Failed to notify guardian of approval expiry');
     });