@vellumai/assistant 0.3.18 → 0.3.20

package/src/permissions/checker.ts

@@ -101,6 +101,19 @@ const WRAPPER_PROGRAMS = new Set([
 // value of -u) as the wrapped program instead of `echo`.
 const ENV_VALUE_FLAGS = new Set(['-u', '--unset', '-C', '--chdir']);
 
+// Bare filenames that `rm` is allowed to delete at Medium risk (instead of
+// High) so workspace-scoped allow rules can approve them without the
+// dangerous `allowHighRisk` flag. Only matches when the args contain no
+// flags and exactly one of these filenames.
+const RM_SAFE_BARE_FILES = new Set(['BOOTSTRAP.md', 'UPDATES.md']);
+
+function isRmOfKnownSafeFile(args: string[]): boolean {
+  if (args.length !== 1) return false;
+  const target = args[0];
+  if (target.startsWith('-') || target.includes('/')) return false;
+  return RM_SAFE_BARE_FILES.has(target);
+}
+
 /**
  * Given a segment whose program is a known wrapper, return the first
  * non-flag argument (i.e. the wrapped program name).  Returns `undefined`
@@ -385,6 +398,13 @@ async function classifyRiskUncached(toolName: string, input: Record<string, unkn
       if (HIGH_RISK_PROGRAMS.has(prog)) return RiskLevel.High;
 
       if (prog === 'rm') {
+        // `rm` of known safe workspace files (no flags, bare filename) is
+        // Medium rather than High so scope-limited allow rules can approve
+        // it without needing allowHighRisk, which would bypass path checks.
+        if (isRmOfKnownSafeFile(seg.args)) {
+          maxRisk = RiskLevel.Medium;
+          continue;
+        }
         return RiskLevel.High;
       }
 
@@ -402,7 +422,14 @@ async function classifyRiskUncached(toolName: string, input: Record<string, unkn
       }
 
       if (WRAPPER_PROGRAMS.has(prog)) {
+        // `command -v` and `command -V` are read-only lookups (print where
+        // a command lives) — don't escalate to high risk for those.
+        if (prog === 'command' && seg.args.length > 0 && (seg.args[0] === '-v' || seg.args[0] === '-V')) {
+          continue;
+        }
         const wrapped = getWrappedProgram(seg);
+        if (wrapped === 'rm') return RiskLevel.High;
+        if (wrapped && HIGH_RISK_PROGRAMS.has(wrapped)) return RiskLevel.High;
         if (wrapped === 'curl' || wrapped === 'wget') {
           maxRisk = RiskLevel.Medium;
           continue;

package/src/runtime/channel-approval-types.ts

@@ -7,6 +7,8 @@
  * same approval flow can be reused across transports.
  */
 
+import type { GuardianDecisionAction } from './guardian-decision-types.js';
+
 // ---------------------------------------------------------------------------
 // Approval actions
 // ---------------------------------------------------------------------------
@@ -20,12 +22,20 @@ export interface ApprovalActionOption {
   label: string;
 }
 
-/** Default action options presented to users across all channels. */
-export const DEFAULT_APPROVAL_ACTIONS: readonly ApprovalActionOption[] = [
-  { id: 'approve_once', label: 'Approve once' },
-  { id: 'approve_always', label: 'Approve always' },
-  { id: 'reject', label: 'Reject' },
-] as const;
+/**
+ * Map `GuardianDecisionAction[]` to `ApprovalActionOption[]` so channel
+ * prompt payloads can be derived from the unified decision action set.
+ * The `action` field from GuardianDecisionAction maps to the `id` field
+ * on ApprovalActionOption (both are canonical action identifiers).
+ */
+export function toApprovalActionOptions(
+  actions: GuardianDecisionAction[],
+): ApprovalActionOption[] {
+  return actions.map(a => ({
+    id: a.action as ApprovalAction,
+    label: a.label,
+  }));
+}
 
 // ---------------------------------------------------------------------------
 // Approval prompt

package/src/runtime/channel-approvals.ts

@@ -17,7 +17,8 @@ import type {
   ApprovalUIMetadata,
   ChannelApprovalPrompt,
 } from './channel-approval-types.js';
-import { DEFAULT_APPROVAL_ACTIONS } from './channel-approval-types.js';
+import { toApprovalActionOptions } from './channel-approval-types.js';
+import { buildDecisionActions, buildPlainTextFallback } from './guardian-decision-types.js';
 import * as pendingInteractions from './pending-interactions.js';
 
 /** Summary of a pending interaction, used by channel approval flows. */
@@ -69,6 +70,11 @@ export function getApprovalInfoByConversation(conversationId: string): PendingAp
 
 /**
  * Internal helper: turn a PendingApprovalInfo into a ChannelApprovalPrompt.
+ *
+ * Derives actions from the shared `buildDecisionActions` builder defined in
+ * guardian-decision-types.ts, then maps them to the channel-facing
+ * `ApprovalActionOption` shape. This ensures channel button sets are always
+ * consistent with the unified `GuardianDecisionPrompt` type.
  */
 function buildPromptFromApprovalInfo(info: PendingApprovalInfo): ChannelApprovalPrompt {
   const promptText = composeApprovalMessage({
@@ -76,15 +82,11 @@ function buildPromptFromApprovalInfo(info: PendingApprovalInfo): ChannelApproval
     toolName: info.toolName,
   });
 
-  // Hide "approve always" when persistent trust rules are disallowed for this invocation.
-  const actions = info.persistentDecisionsAllowed === false
-    ? DEFAULT_APPROVAL_ACTIONS.filter((a) => a.id !== 'approve_always')
-    : [...DEFAULT_APPROVAL_ACTIONS];
-
-  // Plain-text fallback must remain parser-compatible (contains "yes"/"always"/"no" keywords).
-  const plainTextFallback = info.persistentDecisionsAllowed === false
-    ? `${promptText}\n\nReply "yes" to approve or "no" to reject.`
-    : `${promptText}\n\nReply "yes" to approve once, "always" to approve always, or "no" to reject.`;
+  const decisionActions = buildDecisionActions({
+    persistentDecisionsAllowed: info.persistentDecisionsAllowed,
+  });
+  const actions = toApprovalActionOptions(decisionActions);
+  const plainTextFallback = buildPlainTextFallback(promptText, decisionActions);
 
   return { promptText, actions, plainTextFallback };
 }
@@ -199,6 +201,10 @@ export function handleChannelDecision(
  * Build an approval prompt that includes context about which non-guardian
  * user is requesting the action. Sent to the guardian's chat so they
  * can approve or deny on behalf of the requester.
+ *
+ * Uses the shared `buildDecisionActions` builder with `forGuardianOnBehalf`
+ * set to true, which excludes `approve_always` since guardians cannot
+ * permanently allowlist tools on behalf of requesters.
  */
 export function buildGuardianApprovalPrompt(
   info: PendingApprovalInfo,
@@ -210,11 +216,9 @@ export function buildGuardianApprovalPrompt(
     requesterIdentifier,
   });
 
-  // Guardian approvals are always one-time decisions — "approve always"
-  // doesn't make sense when the guardian is approving on behalf of someone else.
-  const actions = DEFAULT_APPROVAL_ACTIONS.filter((a) => a.id !== 'approve_always');
-
-  const plainTextFallback = `${promptText}\n\nReply "yes" to approve or "no" to reject.`;
+  const decisionActions = buildDecisionActions({ forGuardianOnBehalf: true });
+  const actions = toApprovalActionOptions(decisionActions);
+  const plainTextFallback = buildPlainTextFallback(promptText, decisionActions);
 
   return { promptText, actions, plainTextFallback };
 }

package/src/runtime/channel-invite-transport.ts

@@ -0,0 +1,85 @@
+/**
+ * Channel invite transport abstraction.
+ *
+ * Defines a transport interface for building shareable invite links and
+ * extracting inbound invite tokens from channel-specific payloads. Each
+ * channel (Telegram, SMS, Slack, etc.) registers an adapter that knows
+ * how to construct deep links and parse incoming tokens for that channel.
+ *
+ * The transport layer is intentionally thin: it handles URL construction
+ * and token extraction only. Redemption logic lives in
+ * `invite-redemption-service.ts`.
+ */
+
+import type { ChannelId } from '../channels/types.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface InviteSharePayload {
+  /** The full URL the recipient can open to redeem the invite. */
+  url: string;
+  /** Human-readable text suitable for display alongside the link. */
+  displayText: string;
+}
+
+export interface ChannelInviteTransport {
+  /** The channel this transport handles. */
+  channel: ChannelId;
+
+  /**
+   * Build a shareable invite payload (URL + display text) from a raw token.
+   *
+   * The raw token is the base64url-encoded secret returned by
+   * `ingress-invite-store.createInvite`. The transport wraps it in a
+   * channel-specific deep link so the recipient can redeem the invite
+   * by clicking/tapping the link.
+   */
+  buildShareableInvite(params: {
+    rawToken: string;
+    sourceChannel: ChannelId;
+  }): InviteSharePayload;
+
+  /**
+   * Extract an invite token from an inbound channel message.
+   *
+   * Returns the raw token string (without the `iv_` prefix) if the
+   * message contains a valid invite token, or `undefined` otherwise.
+   */
+  extractInboundToken(params: {
+    commandIntent?: Record<string, unknown>;
+    content: string;
+    sourceMetadata?: Record<string, unknown>;
+  }): string | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+const registry = new Map<ChannelId, ChannelInviteTransport>();
+
+/**
+ * Register a channel invite transport. Overwrites any previously registered
+ * transport for the same channel.
+ */
+export function registerTransport(transport: ChannelInviteTransport): void {
+  registry.set(transport.channel, transport);
+}
+
+/**
+ * Look up the registered transport for a channel. Returns `undefined` when
+ * no transport has been registered for the given channel.
+ */
+export function getTransport(channel: ChannelId): ChannelInviteTransport | undefined {
+  return registry.get(channel);
+}
+
+/**
+ * Reset the registry. Intended for tests only.
+ * @internal
+ */
+export function _resetRegistry(): void {
+  registry.clear();
+}

package/src/runtime/channel-invite-transports/telegram.ts

@@ -0,0 +1,105 @@
+/**
+ * Telegram channel invite transport adapter.
+ *
+ * Builds `https://t.me/<botUsername>?start=iv_<token>` deep links and
+ * extracts invite tokens from `/start iv_<token>` command payloads.
+ *
+ * The `iv_` prefix distinguishes invite tokens from `gv_` (guardian
+ * verification) tokens that use the same `/start` deep-link mechanism.
+ */
+
+import type { ChannelId } from '../../channels/types.js';
+import { getCredentialMetadata } from '../../tools/credentials/metadata-store.js';
+import {
+  type ChannelInviteTransport,
+  type InviteSharePayload,
+  registerTransport,
+} from '../channel-invite-transport.js';
+
+// ---------------------------------------------------------------------------
+// Bot username resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the Telegram bot username from credential metadata, falling back
+ * to the TELEGRAM_BOT_USERNAME environment variable. Mirrors the resolution
+ * strategy used in `guardian-outbound-actions.ts`.
+ */
+function getTelegramBotUsername(): string | undefined {
+  const meta = getCredentialMetadata('telegram', 'bot_token');
+  if (meta?.accountInfo && typeof meta.accountInfo === 'string' && meta.accountInfo.trim().length > 0) {
+    return meta.accountInfo.trim();
+  }
+  return process.env.TELEGRAM_BOT_USERNAME || undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Token prefix
+// ---------------------------------------------------------------------------
+
+const INVITE_TOKEN_PREFIX = 'iv_';
+
+// ---------------------------------------------------------------------------
+// Transport implementation
+// ---------------------------------------------------------------------------
+
+export const telegramInviteTransport: ChannelInviteTransport = {
+  channel: 'telegram' as ChannelId,
+
+  buildShareableInvite(params: {
+    rawToken: string;
+    sourceChannel: ChannelId;
+  }): InviteSharePayload {
+    const botUsername = getTelegramBotUsername();
+    if (!botUsername) {
+      throw new Error('Telegram bot username is not configured. Set up the Telegram integration first.');
+    }
+
+    const url = `https://t.me/${botUsername}?start=${INVITE_TOKEN_PREFIX}${params.rawToken}`;
+    return {
+      url,
+      displayText: `Open in Telegram: ${url}`,
+    };
+  },
+
+  extractInboundToken(params: {
+    commandIntent?: Record<string, unknown>;
+    content: string;
+    sourceMetadata?: Record<string, unknown>;
+  }): string | undefined {
+    // Primary path: structured command intent from the gateway.
+    // The gateway normalizes `/start <payload>` into
+    // `{ type: 'start', payload: '<payload>' }`.
+    if (
+      params.commandIntent &&
+      params.commandIntent.type === 'start' &&
+      typeof params.commandIntent.payload === 'string'
+    ) {
+      const payload = params.commandIntent.payload;
+      if (payload.startsWith(INVITE_TOKEN_PREFIX)) {
+        const token = payload.slice(INVITE_TOKEN_PREFIX.length);
+        // Reject empty or whitespace-only tokens
+        if (token.length > 0 && token.trim().length > 0) {
+          return token;
+        }
+      }
+      return undefined;
+    }
+
+    // Fallback: raw content parsing for `/start iv_<token>` messages.
+    // This handles cases where the gateway forwards the raw command text
+    // without a structured commandIntent.
+    const match = params.content.match(/^\/start\s+iv_(\S+)/);
+    if (match && match[1] && match[1].length > 0) {
+      return match[1];
+    }
+
+    return undefined;
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Auto-register on import
+// ---------------------------------------------------------------------------
+
+registerTransport(telegramInviteTransport);

package/src/runtime/guardian-action-grant-minter.ts

@@ -0,0 +1,154 @@
+/**
+ * Shared helper for minting scoped approval grants when a guardian-action
+ * request is resolved with tool metadata.
+ *
+ * Used by both the channel inbound path (inbound-message-handler.ts) and
+ * the desktop/IPC path (session-process.ts) to ensure grants are minted
+ * consistently regardless of which channel the guardian answers on.
+ */
+
+import { mintGrantFromDecision } from '../approvals/approval-primitive.js';
+import type { GuardianActionRequest } from '../memory/guardian-action-store.js';
+import { getLogger } from '../util/logger.js';
+import { runApprovalConversationTurn } from './approval-conversation-turn.js';
+import { parseApprovalDecision } from './channel-approval-parser.js';
+import type { ApprovalConversationGenerator } from './http-types.js';
+
+const log = getLogger('guardian-action-grant-minter');
+
+/** TTL for scoped approval grants minted on guardian-action answer resolution. */
+export const GUARDIAN_ACTION_GRANT_TTL_MS = 5 * 60 * 1000;
+
+/**
+ * Mint a `tool_signature` scoped grant when a guardian-action request is
+ * resolved and the request carries tool metadata (toolName + inputDigest).
+ *
+ * Uses two-tier classification:
+ *   1. Deterministic fast path via parseApprovalDecision (exact keyword match).
+ *   2. LLM fallback via runApprovalConversationTurn when the deterministic
+ *      parser returns null and an approvalConversationGenerator is provided.
+ *
+ * Skips silently when:
+ *   - The resolved request has no toolName/inputDigest (informational consult).
+ *   - The guardian's answer is not classified as approval by either tier (fail-closed).
+ *
+ * Fails silently on error -- grant minting is best-effort and must never
+ * block the guardian-action answer flow.
+ */
+export async function tryMintGuardianActionGrant(params: {
+  request: GuardianActionRequest;
+  answerText: string;
+  decisionChannel: string;
+  guardianExternalUserId?: string;
+  approvalConversationGenerator?: ApprovalConversationGenerator;
+}): Promise<void> {
+  const { request, answerText, decisionChannel, guardianExternalUserId, approvalConversationGenerator } = params;
+
+  // Only mint for requests that carry tool metadata -- informational
+  // ASK_GUARDIAN consults without tool context do not produce grants.
+  if (!request.toolName || !request.inputDigest) {
+    return;
+  }
+
+  // Tier 1: Deterministic fast path -- try exact keyword matching first.
+  // Guardian-action invariant: grants are always one-time `tool_signature`
+  // scoped.  We treat `approve_always` from the deterministic parser the
+  // same as `approve_once` -- the grant is still single-use.  This keeps
+  // the guardian-action path aligned with the primary approval interception
+  // flow where guardians are limited to approve_once / reject.
+  const decision = parseApprovalDecision(answerText);
+  let isApproval = decision?.action === 'approve_once' || decision?.action === 'approve_always';
+
+  // Tier 2: LLM fallback -- when the deterministic parser found no match
+  // and a generator is available, delegate to the conversational engine.
+  // Only allow approve_once (not approve_always) to keep guardian-action
+  // grants strictly one-time and consistent with guardian policy.
+  if (!isApproval && !decision && approvalConversationGenerator) {
+    try {
+      const llmResult = await runApprovalConversationTurn(
+        {
+          toolName: request.toolName,
+          allowedActions: ['approve_once', 'reject'],
+          role: 'guardian',
+          pendingApprovals: [{ requestId: request.id, toolName: request.toolName }],
+          userMessage: answerText,
+        },
+        approvalConversationGenerator,
+      );
+
+      isApproval = llmResult.disposition === 'approve_once';
+
+      log.info(
+        {
+          event: 'guardian_action_grant_llm_fallback',
+          toolName: request.toolName,
+          requestId: request.id,
+          answerText,
+          llmDisposition: llmResult.disposition,
+          matched: isApproval,
+          decisionChannel,
+        },
+        `LLM fallback classifier returned disposition: ${llmResult.disposition}`,
+      );
+    } catch (err) {
+      // Fail-closed: generator errors must not produce grants.
+      log.warn(
+        {
+          event: 'guardian_action_grant_llm_fallback_error',
+          toolName: request.toolName,
+          requestId: request.id,
+          err,
+          decisionChannel,
+        },
+        'LLM fallback classifier threw an error; treating as non-approval (fail-closed)',
+      );
+    }
+  }
+
+  if (!isApproval) {
+    log.info(
+      {
+        event: 'guardian_action_grant_skipped_no_approval',
+        toolName: request.toolName,
+        requestId: request.id,
+        answerText,
+        parsedAction: decision?.action ?? null,
+        decisionChannel,
+      },
+      'Skipped grant minting: guardian answer not classified as approval',
+    );
+    return;
+  }
+
+  const result = mintGrantFromDecision({
+    assistantId: request.assistantId,
+    scopeMode: 'tool_signature',
+    toolName: request.toolName,
+    inputDigest: request.inputDigest,
+    requestChannel: request.sourceChannel,
+    decisionChannel,
+    executionChannel: null,
+    conversationId: request.sourceConversationId,
+    callSessionId: request.callSessionId,
+    guardianExternalUserId: guardianExternalUserId ?? null,
+    expiresAt: new Date(Date.now() + GUARDIAN_ACTION_GRANT_TTL_MS).toISOString(),
+  });
+
+  if (result.ok) {
+    log.info(
+      {
+        event: 'guardian_action_grant_minted',
+        toolName: request.toolName,
+        requestId: request.id,
+        callSessionId: request.callSessionId,
+        decisionChannel,
+      },
+      'Minted scoped approval grant for guardian-action answer resolution',
+    );
+  } else {
+    log.error(
+      { reason: result.reason, toolName: request.toolName, requestId: request.id },
+      'Failed to mint scoped approval grant for guardian-action (non-fatal)',
+    );
+  }
+}

package/src/runtime/guardian-action-message-composer.ts

@@ -26,11 +26,16 @@ export type GuardianActionMessageScenario =
   | 'guardian_followup_failed'
   | 'guardian_followup_declined_ack'
   | 'guardian_followup_clarification'
+  | 'guardian_pending_disambiguation'
   | 'guardian_expired_disambiguation'
   | 'guardian_followup_disambiguation'
   | 'guardian_stale_answered'
   | 'guardian_stale_expired'
   | 'guardian_stale_followup'
+  | 'guardian_stale_superseded'
+  | 'guardian_superseded_remap'
+  | 'guardian_unknown_code'
+  | 'guardian_auto_matched'
   | 'outbound_message_copy'
   | 'followup_message_sent'
   | 'followup_call_started'
@@ -48,6 +53,10 @@ export interface GuardianActionMessageContext {
   failureReason?: string;
   counterpartyPhone?: string;
   requestCodes?: string[];
+  /** The code the guardian provided that was not recognized. */
+  unknownCode?: string;
+  /** The code of the active request that supersedes the one the guardian targeted. */
+  activeRequestCode?: string;
 }
 
 export interface ComposeGuardianActionMessageOptions {
@@ -181,6 +190,11 @@ export function getGuardianActionFallbackMessage(context: GuardianActionMessageC
     case 'guardian_followup_clarification':
       return "Sorry, I didn't quite catch that. Would you like to call them back, send them a message, or skip it for now?";
 
+    case 'guardian_pending_disambiguation':
+      return listedCodes
+        ? `You have multiple pending guardian questions. Please prefix your reply with the reference code (${listedCodes}) so I know which question you're answering.`
+        : 'You have multiple pending guardian questions. Please prefix your reply with the reference code so I know which question you\'re answering.';
+
     case 'guardian_expired_disambiguation':
       return listedCodes
         ? `You have multiple expired guardian questions. Please prefix your reply with the reference code (${listedCodes}) so I know which question you're answering.`
@@ -200,6 +214,22 @@ export function getGuardianActionFallbackMessage(context: GuardianActionMessageC
     case 'guardian_stale_followup':
       return 'It looks like this follow-up has already been handled. No further action is needed.';
 
+    case 'guardian_stale_superseded':
+      return 'This request is no longer active. The call has ended and no further action is needed.';
+
+    case 'guardian_unknown_code':
+      return context.unknownCode
+        ? `I don't recognize the code "${context.unknownCode}". Please check the reference code and try again.`
+        : "I don't recognize that reference code. Please check the code and try again.";
+
+    case 'guardian_auto_matched':
+      return 'Got it, routing your answer to the active request.';
+
+    case 'guardian_superseded_remap':
+      return context.questionText
+        ? `Got it! Your answer has been applied to the current active request: "${context.questionText}"`
+        : 'Got it! Your answer has been applied to the current active request on the call.';
+
     case 'outbound_message_copy':
       // This SMS is sent TO the original caller relaying the guardian's answer.
       // When lateAnswerText is available, include it — that's the whole point of message_back.

package/src/runtime/guardian-decision-types.ts

@@ -0,0 +1,91 @@
+/**
+ * Shared types for the guardian decision primitive.
+ *
+ * All decision entrypoints (callback buttons, conversational engine, legacy
+ * parser, requester self-cancel) use these types to route through the
+ * unified `applyGuardianDecision` primitive.
+ */
+
+// ---------------------------------------------------------------------------
+// Guardian decision prompt
+// ---------------------------------------------------------------------------
+
+/** Structured model for prompts shown to guardians. */
+export interface GuardianDecisionPrompt {
+  requestId: string;
+  /** Short human-readable code for the request. */
+  requestCode: string;
+  state: 'pending' | 'followup_awaiting_choice' | 'expired_superseded_with_active_call';
+  questionText: string;
+  toolName: string | null;
+  actions: GuardianDecisionAction[];
+  expiresAt: number;
+  conversationId: string;
+  callSessionId: string | null;
+}
+
+export interface GuardianDecisionAction {
+  /** Canonical action identifier. */
+  action: string;
+  /** Human-readable label for the action. */
+  label: string;
+}
+
+// ---------------------------------------------------------------------------
+// Shared decision action constants
+// ---------------------------------------------------------------------------
+
+/** Canonical set of all guardian decision actions with their labels. */
+export const GUARDIAN_DECISION_ACTIONS = {
+  approve_once:   { action: 'approve_once',   label: 'Approve once' },
+  approve_always: { action: 'approve_always', label: 'Approve always' },
+  reject:         { action: 'reject',         label: 'Reject' },
+} as const satisfies Record<string, GuardianDecisionAction>;
+
+/**
+ * Build the set of `GuardianDecisionAction` items appropriate for a prompt,
+ * respecting whether persistent decisions (approve_always) are allowed.
+ *
+ * When `persistentDecisionsAllowed` is `false`, the `approve_always` action
+ * is excluded. When `forGuardianOnBehalf` is `true` (guardian acting on behalf
+ * of a requester), `approve_always` is also excluded since guardians cannot
+ * permanently allowlist tools on behalf of others.
+ */
+export function buildDecisionActions(opts?: {
+  persistentDecisionsAllowed?: boolean;
+  forGuardianOnBehalf?: boolean;
+}): GuardianDecisionAction[] {
+  const showAlways = opts?.persistentDecisionsAllowed !== false && !opts?.forGuardianOnBehalf;
+  return [
+    GUARDIAN_DECISION_ACTIONS.approve_once,
+    ...(showAlways ? [GUARDIAN_DECISION_ACTIONS.approve_always] : []),
+    GUARDIAN_DECISION_ACTIONS.reject,
+  ];
+}
+
+/**
+ * Build the plain-text fallback instruction string that matches the given
+ * set of decision actions. Ensures the text always includes parser-compatible
+ * keywords (yes/always/no) so text-based fallback remains actionable.
+ */
+export function buildPlainTextFallback(
+  promptText: string,
+  actions: GuardianDecisionAction[],
+): string {
+  const hasAlways = actions.some(a => a.action === 'approve_always');
+  return hasAlways
+    ? `${promptText}\n\nReply "yes" to approve once, "always" to approve always, or "no" to reject.`
+    : `${promptText}\n\nReply "yes" to approve or "no" to reject.`;
+}
+
+// ---------------------------------------------------------------------------
+// Apply decision result
+// ---------------------------------------------------------------------------
+
+export interface ApplyGuardianDecisionResult {
+  applied: boolean;
+  reason?: 'stale' | 'identity_mismatch' | 'invalid_action' | 'not_found' | 'expired';
+  requestId?: string;
+  /** Feedback text when the action was parsed from user text. */
+  userText?: string;
+}