@vellumai/assistant 0.11.1 → 0.11.2-staging.2

package/src/calls/call-setup-router.ts

@@ -20,6 +20,7 @@ import { DAEMON_INTERNAL_ASSISTANT_ID } from "../runtime/assistant-scope.js";
 import {
   type AdmissionPolicyResult,
   enforceAdmissionPolicy,
+  trustedContactPromotionClearsFloor,
 } from "../runtime/routes/inbound-stages/admission-policy.js";
 import {
   actorTrustContextFromVerdict,
@@ -260,13 +261,20 @@ export async function routeSetup(ctx: SetupContext): Promise<{
       : await getPendingSession("phone");
 
   // An admission floor is "active" only when a policy applies and no pending
-  // verification challenge is in flight. While active, the floor IS the access
-  // decision: an admitted caller bypasses the legacy identity flows
-  // (unverified_caller / name_capture) and connects directly. When inactive
-  // (null policy, flag off, exempt channel, or a pending challenge), those
-  // legacy flows are preserved unchanged.
+  // verification challenge is in flight. While active, an admitted caller
+  // bypasses the legacy identity flows (unverified_caller / name_capture) and
+  // connects directly. When inactive (null policy, flag off, exempt channel,
+  // or a pending challenge), those legacy flows are preserved unchanged.
   const floorActive = ctx.admissionPolicy != null && !pendingChallenge;
 
+  // Whether a guardian approval could lift a below-floor caller past this
+  // floor. On floors it can clear, a floor deny routes the caller into the
+  // guardian access-request flow instead of hanging up on them (see the
+  // unknown-caller branch below).
+  const approvalCouldClearFloor =
+    ctx.admissionPolicy != null &&
+    trustedContactPromotionClearsFloor(ctx.admissionPolicy);
+
   // Inbound admission floor verdict; defaults to admitted when inactive.
   const floorVerdict = floorActive
     ? enforceAdmissionPolicy({
@@ -303,6 +311,36 @@ export async function routeSetup(ctx: SetupContext): Promise<{
     };
   };
 
+  // Members whose channel the guardian set to `policy: 'deny'`. This gate is
+  // trust-class independent and runs ahead of every inbound flow below: the
+  // gateway derives trust class from channel STATUS alone, so a denied channel
+  // still resolves to `unverified_contact` (status `unverified`/`pending`) or
+  // `trusted_contact` (status `active`). Gating per class would leave the deny
+  // unenforced for whichever classes the branch order happened to exclude.
+  //
+  // It also outranks an active voice invite: an explicit channel-level deny is
+  // the guardian's standing ruling, and an invite must not redeem past it into
+  // a trusted contact.
+  if (actorTrust.memberRecord?.policy === "deny") {
+    log.info(
+      {
+        callSessionId: ctx.callSessionId,
+        from: ctx.from,
+        channelId: actorTrust.memberRecord.channel.id,
+        trustClass: actorTrust.trustClass,
+      },
+      "Inbound voice ACL: member policy deny",
+    );
+    return {
+      outcome: {
+        action: "deny",
+        message: "This number is not authorized to use this assistant.",
+        logReason: "Inbound voice ACL: member policy deny",
+      },
+      resolved,
+    };
+  }
+
   if (
     (actorTrust.trustClass === "unknown" ||
       actorTrust.trustClass === "unverified_contact") &&
@@ -350,19 +388,46 @@ export async function routeSetup(ctx: SetupContext): Promise<{
       };
     }
 
-    // When a floor is active it is the access decision: an admitted caller
-    // connects directly (skipping unverified_caller / name_capture), and a
-    // below-floor caller is denied. Invites (handled above) bypass the floor
-    // as an explicit grant. When the floor is inactive (null policy), fall
-    // through to the legacy identity flows below.
+    // A caller who clears the floor connects directly, skipping
+    // unverified_caller / name_capture. Invites (handled above) bypass the
+    // floor as an explicit grant.
+    //
+    // A caller BELOW the floor is not simply hung up on: when a guardian
+    // approval could admit them, fall through to the legacy identity flows
+    // below, which capture the caller's name, raise a guardian access request,
+    // and hold the line for the decision. The floor still governs the outcome,
+    // because the flow only ever admits a caller the guardian approved into a
+    // trusted contact.
+    //
+    // Two cases keep the hard deny. Floors a trusted-contact promotion could
+    // not clear (`guardian_only`, `no_one`), where an approval flow would
+    // promise a decision that cannot admit the caller. And `blocked` /
+    // `revoked` members, who should hear the denial rather than an invitation
+    // to identify themselves. (The third governance signal, a channel
+    // `policy` of `deny`, is gated ahead of this whole branch.)
     if (floorActive) {
-      if (!floorVerdict.admitted) {
+      if (floorVerdict.admitted) {
+        return {
+          outcome: { action: "normal_call" as const, isInbound: true },
+          resolved,
+        };
+      }
+      if (
+        !approvalCouldClearFloor ||
+        floorVerdict.reason === "member_blocked" ||
+        floorVerdict.reason === "member_revoked"
+      ) {
         return floorDeny(floorVerdict);
       }
-      return {
-        outcome: { action: "normal_call" as const, isInbound: true },
-        resolved,
-      };
+      log.info(
+        {
+          callSessionId: ctx.callSessionId,
+          from: ctx.from,
+          trustClass: actorTrust.trustClass,
+          effectivePolicy: floorVerdict.effectivePolicy,
+        },
+        "Inbound voice ACL: caller below admission floor, routing to guardian access request",
+      );
     }
 
     // Known caller whose channel hasn't passed verification yet —
@@ -413,27 +478,6 @@ export async function routeSetup(ctx: SetupContext): Promise<{
     };
   }
 
-  // Members with policy: 'deny'
-  if (actorTrust.memberRecord?.policy === "deny") {
-    log.info(
-      {
-        callSessionId: ctx.callSessionId,
-        from: ctx.from,
-        channelId: actorTrust.memberRecord.channel.id,
-        trustClass: actorTrust.trustClass,
-      },
-      "Inbound voice ACL: member policy deny",
-    );
-    return {
-      outcome: {
-        action: "deny",
-        message: "This number is not authorized to use this assistant.",
-        logReason: "Inbound voice ACL: member policy deny",
-      },
-      resolved,
-    };
-  }
-
   // Guardian verification challenge
   if (pendingChallenge) {
     return {

package/src/calls/voice-session-bridge.ts

@@ -40,6 +40,7 @@ import { getCurrentSeq } from "../runtime/assistant-stream-state.js";
 import { publishConversationMessagesChanged } from "../runtime/sync/resource-sync-events.js";
 import { computeToolApprovalDigest } from "../security/tool-approval-digest.js";
 import { getAllTools } from "../tools/registry.js";
+import { sensitiveToolReach } from "../tools/tool-approval-handler.js";
 import { createAbortReason } from "../util/abort-reasons.js";
 import { getLogger } from "../util/logger.js";
 import { truncate } from "../util/truncate.js";
@@ -286,6 +287,28 @@ export interface VoiceTurnOptions {
   onError?: (message: string) => void;
   /** Event-name callbacks used by non-phone voice clients. */
   callbacks?: VoiceTurnCallbacks;
+  /**
+   * Called when this turn leaves a confirmation for the user to answer instead
+   * of deciding it, so the client can put the prompt where they can see it.
+   *
+   * A voice client renders its call as something that covers the app (the
+   * live-voice room is a full-screen overlay), which is fine while the call is
+   * the only thing happening and wrong the moment the turn is waiting on a
+   * decision: the card is on screen, behind the call. The bridge cannot reach
+   * a client's own surfaces, so it says *that a decision is waiting* and the
+   * client decides what to do about it.
+   */
+  onApprovalPending?: (requestId: string) => void;
+  /**
+   * Called when the last pending confirmation this turn was waiting on is
+   * decided, however it was decided (the user answered, it timed out, a newer
+   * message superseded it). Paired with {@link onApprovalPending} so a client
+   * that changed its presentation for the wait can change it back.
+   *
+   * Fires on the *last* one, not each: a turn waiting on two decisions is
+   * still waiting after the first is answered.
+   */
+  onApprovalsResolved?: () => void;
   /** Optional AbortSignal for external cancellation (e.g. barge-in). */
   signal?: AbortSignal;
   /**
@@ -367,12 +390,27 @@ export interface VoiceTurnHandle {
  * provides assistant identity) and guardian context (injected separately).
  */
 /**
- * Steering shared by every voice channel. Voice turns exclude the ui-surface
- * tools, but the model can still reach OAuth/sign-in flows through shell or
- * CLI tools (e.g. `assistant oauth connect`), which open a browser window
- * mid-call that the caller may be unable to see or complete. Tell it to speak
- * the limitation and defer the flow to text chat instead.
+ * Steering shared by every voice channel. A sign-in flow opens a browser
+ * window mid-call that the caller may be unable to see or complete, whether it
+ * is reached through a ui-surface tool or through shell and CLI tools (e.g.
+ * `assistant oauth connect`). Tell the model to speak the limitation and defer
+ * the flow to text chat instead.
+ *
+ * This outlives the ui-surface restriction it was written alongside: a
+ * live-voice call can now show surfaces, but a browser window handing control
+ * to a third party mid-call is a different problem, and one a minimized room
+ * does not solve.
  */
+/**
+ * How long a live-voice call waits on an approval before deciding it itself.
+ *
+ * Long enough to pick the phone up and read the card, short enough that a turn
+ * cannot sit blocked for the rest of the call. The fallback is the decision
+ * this channel made before it prompted at all, so the worst case of nobody
+ * answering is exactly the old behavior, arrived at late.
+ */
+const VOICE_APPROVAL_TIMEOUT_MS = 45_000;
+
 export const VOICE_NO_SETUP_FLOWS_RULE =
   "Never start account connections, OAuth or sign-in flows, or any other action that opens a browser window or needs the user's screen during this call — not even through shell or CLI tools. If the task needs one, say so briefly and offer to finish it in text chat after the call.";
 
@@ -851,7 +889,37 @@ export async function startVoiceTurn(
   // (tracked via `clientCallbackInstalled`); otherwise cleanup would detach
   // an active sender installed by a prior turn.
   let clientCallbackInstalled = false;
+  /**
+   * Confirmations this voice turn left pending for the user to answer, and the
+   * timers that stop them waiting forever.
+   *
+   * A call is a poor place to block: the user may have put the phone in a
+   * pocket, and a turn that waits indefinitely is a session that looks wedged.
+   * Each pending request therefore carries a deadline, after which it resolves
+   * the way this channel resolved everything before it prompted at all.
+   */
+  const pendingVoiceApprovals = new Map<
+    string,
+    ReturnType<typeof setTimeout>
+  >();
+  const settleVoiceApproval = (requestId: string): void => {
+    const timer = pendingVoiceApprovals.get(requestId);
+    if (timer === undefined) {
+      // Not one of ours: other interactions (secrets, host-proxy requests)
+      // resolve through the same event.
+      return;
+    }
+    clearTimeout(timer);
+    pendingVoiceApprovals.delete(requestId);
+    if (pendingVoiceApprovals.size === 0) {
+      opts.onApprovalsResolved?.();
+    }
+  };
   const cleanup = () => {
+    for (const timer of pendingVoiceApprovals.values()) {
+      clearTimeout(timer);
+    }
+    pendingVoiceApprovals.clear();
     conversation.setChannelCapabilities(null);
     conversation.setTrustContext(null);
     conversation.setCommandIntent(null);
@@ -872,7 +940,12 @@ export async function startVoiceTurn(
     const persistResult = await conversation.persistUserMessage({
       content: persistedContent,
       requestId,
-      ...(isHiddenSyntheticPrompt ? { metadata: { hidden: true } } : {}),
+      metadata: {
+        // Durable "this turn came from an open voice session" marker; see
+        // `isVoiceSessionUserMessage` for why the channel fields cannot carry it.
+        voiceSessionTurn: true,
+        ...(isHiddenSyntheticPrompt ? { hidden: true } : {}),
+      },
     });
     return persistResult.id;
   };
@@ -892,21 +965,22 @@ export async function startVoiceTurn(
     trustContext: opts.trustContext ?? null,
     turnChannelContext,
     turnInterfaceContext,
-    channelCapabilities: {
-      ...resolveChannelCapabilities(
-        turnChannelContext.userMessageChannel,
-        turnInterfaceContext.userMessageInterface,
-      ),
-      // Voice calls are non-interactive: no surface can be shown, read, or
-      // clicked mid-call, so `ui_show`/`ui_update`/`ui_dismiss` (and thus
-      // `oauth_connect`, a ui_show surface_type) must never reach the model.
-      // Phone already resolves to false via its channel; live-voice resolves
-      // vellum/macos → true, so force it off here for every voice turn. This
-      // also flips the runtime-context `supports_dynamic_ui` line the prompt
-      // advertises, the secret-prompter's dynamic-UI branch, and the
-      // task-progress-nudge hook — all correctly non-UI during a call.
-      supportsDynamicUi: false,
-    },
+    // Resolved from the channel, with no voice-specific override.
+    //
+    // Whether a call can show a surface is a property of the call's channel,
+    // not of calls in general. A phone call has no screen at all and resolves
+    // to `supportsDynamicUi: false` on its own; a live-voice call is a screen
+    // the user is holding, temporarily covered by the room overlay, and the
+    // session minimizes that overlay when a surface is shown (see the ui-tool
+    // branch of the live-voice session's `tool_use_start`).
+    //
+    // This one flag also drives the runtime-context `supports_dynamic_ui`
+    // line, the secret-prompter's dynamic-UI branch, and the
+    // task-progress-nudge hook, so a live-voice turn now reaches all of them.
+    channelCapabilities: resolveChannelCapabilities(
+      turnChannelContext.userMessageChannel,
+      turnInterfaceContext.userMessageInterface,
+    ),
     voiceCallControlPrompt,
   };
   const installVoiceTurnState = () => {
@@ -1105,6 +1179,11 @@ export async function startVoiceTurn(
   // Voice auto-denies/auto-allows/auto-resolves these since there's no interactive UI.
   let lastError: string | null = null;
   conversation.updateClient(async (msg: AssistantEvent) => {
+    // The user (or anything else) answered: stop the fallback from firing on a
+    // request that is already decided.
+    if (msg.type === "interaction_resolved") {
+      settleVoiceApproval(msg.requestId);
+    }
     if (msg.type === "confirmation_request") {
       // Broadcast the request BEFORE resolving it: resolution synchronously
       // broadcasts `interaction_resolved` (handleConfirmationResponse →
@@ -1181,6 +1260,71 @@ export async function startVoiceTurn(
         });
         return;
       }
+      // A live-voice call has a screen, so a consequential action can be put
+      // to the user instead of decided for them.
+      //
+      // Everything used to be allowed here on the strength of the caller being
+      // a guardian, which made a voice call the one surface where a tool that
+      // writes to the workspace or reaches the host never had to ask. Only
+      // *sensitive* reach prompts: gating every confirmation would interrupt a
+      // conversation constantly, and the tools that read or render were never
+      // the reason approval exists.
+      //
+      // Phone keeps the old behavior in full. There is no screen on that
+      // channel, so a prompt there is a question nobody can answer.
+      // The workspace root is what makes an escape visible. A sandbox file
+      // tool pointed outside the workspace reaches the host filesystem on a
+      // non-containerized install, and `sensitiveToolReach` can only see that
+      // when it is given the boundary to compare against: without it,
+      // `file_read { path: "/etc/hosts" }` classifies as `none` and would fall
+      // through to the auto-allow this branch exists to prevent.
+      const workspaceRoot = conversation.workingDir;
+      const reach = sensitiveToolReach(
+        msg.toolName,
+        // Absent on requests that do not come from the tool pipeline (proxy
+        // and network prompters). Unknown reads as the more consequential of
+        // the two: the cost of being wrong is a prompt the user did not need,
+        // against an unreviewed action on their machine.
+        msg.executionTarget ?? "host",
+        msg.input,
+        workspaceRoot,
+      );
+      const canPrompt = turnChannelContext.userMessageChannel === "vellum";
+      // Fail closed on a missing boundary for the same reason: with no
+      // workspace root there is no way to tell an ordinary write from an
+      // escape, and the safe reading of "cannot tell" is "ask". A real
+      // conversation always has one, so this is a guard rather than a path.
+      if (canPrompt && (reach !== "none" || !workspaceRoot)) {
+        log.info(
+          { turnId, toolName: msg.toolName, reach },
+          "Prompting guardian voice caller for a sensitive tool",
+        );
+        // Left pending: the request is already broadcast, so the approval card
+        // an attached client renders is now answerable rather than cleared a
+        // moment later by this handler.
+        //
+        // Announced separately, because "a card exists" and "the user can see
+        // it" are different things on a channel whose call covers the app.
+        opts.onApprovalPending?.(msg.requestId);
+        const timer = setTimeout(() => {
+          pendingVoiceApprovals.delete(msg.requestId);
+          if (pendingVoiceApprovals.size === 0) {
+            opts.onApprovalsResolved?.();
+          }
+          log.info(
+            { turnId, toolName: msg.toolName },
+            "Voice approval timed out — falling back to the guardian allow",
+          );
+          conversation.handleConfirmationResponse(msg.requestId, "allow", {
+            decisionContext: `Permission approved for "${msg.toolName}": this is a verified guardian voice call and the approval prompt went unanswered.`,
+          });
+        }, VOICE_APPROVAL_TIMEOUT_MS);
+        // Never hold the process open for a prompt nobody is looking at.
+        timer.unref?.();
+        pendingVoiceApprovals.set(msg.requestId, timer);
+        return;
+      }
+
       log.info(
         { turnId, toolName: msg.toolName },
         "Auto-approving confirmation request for guardian voice turn",
@@ -1191,11 +1335,14 @@ export async function startVoiceTurn(
       return;
     }
     if (msg.type === "secret_request") {
-      // Defense-in-depth: SecretPrompter.prompt fails fast with
-      // `unsupported_channel` on voice turns (supportsDynamicUi is forced
-      // off above), so a secret_request should never reach this handler.
-      // Resolve immediately anyway in case an emitter bypasses the
-      // prompter's channel check or races a capability install.
+      // Auto-resolved rather than prompted, on every voice channel.
+      //
+      // A phone call cannot render a secret field at all. A live-voice call
+      // now can (its channel resolves `supportsDynamicUi` true), so this is
+      // where the prompt would surface, and it deliberately does not yet:
+      // typing a credential into a screen you reached by minimizing a call is
+      // a flow that needs designing, not a flag flip. Resolving with no secret
+      // leaves the tool to fail the way it does today.
       log.info(
         { turnId, service: msg.service, field: msg.field },
         "Auto-resolving secret request for voice turn (no secret-entry UI)",

package/src/cli/commands/inference.help.ts

@@ -81,7 +81,7 @@ Examples:
   $ echo "Summarize this" | assistant inference send
   $ assistant llm send --system-prompt "You are a poet" "Write a haiku"
   $ assistant inference send --timeout-seconds 300 "Draft a long memo"
-  $ assistant inference send --model claude-sonnet-4-20250514 --json "Hello"
+  $ assistant inference send --model claude-sonnet-5 --json "Hello"
   $ assistant inference send --profile balanced "Explain RFC 1149"`,
 };
 
@@ -96,7 +96,7 @@ Examples:
   $ assistant inference send "What is the capital of France?"
   $ echo "Explain quantum computing" | assistant inference send
   $ assistant llm send --system-prompt "Be concise" "What is TCP?"
-  $ assistant inference send --model claude-sonnet-4-20250514 --json "Hello"
+  $ assistant inference send --model claude-sonnet-5 --json "Hello"
   $ assistant inference send --profile balanced "Explain RFC 1149"`,
   subcommands: [
     sendSubcommandHelp,
@@ -551,7 +551,7 @@ Examples:
   $ assistant llm send "What is the capital of France?"
   $ echo "Explain quantum computing" | assistant llm send
   $ assistant llm send --system-prompt "Be concise" "What is TCP?"
-  $ assistant llm send --model claude-sonnet-4-20250514 --json "Hello"
+  $ assistant llm send --model claude-sonnet-5 --json "Hello"
   $ assistant llm send --profile balanced "Explain RFC 1149"`,
   subcommands: [sendSubcommandHelp],
 };

package/src/cli/commands/notifications.help.ts

@@ -86,7 +86,7 @@ Examples:
         {
           flags: "--title <title>",
           description:
-            "Short headline (≤ 8 words). Always provide one — the auto-derived fallback just truncates --message.",
+            "Short headline. Titles over 40 characters are trimmed to fit, and one over 40 characters that also runs past 7 words is cut to its first 5. A title that reads like prose (a reasoning opener, or a full sentence ending in terminal punctuation) is discarded in favor of a headline derived from --message.",
         },
         {
           flags: "--urgency <urgency>",
@@ -263,7 +263,8 @@ Examples:
         },
         {
           flags: "--title <title>",
-          description: "New short headline (≤ 8 words).",
+          description:
+            "New short headline (≤ 8 words). An empty value is ignored, so the existing title stays put.",
         },
         {
           flags: "--urgency <urgency>",