@vellumai/assistant 0.10.12 → 0.11.0-staging.1

package/src/acp/__tests__/client-handler.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, test } from "bun:test";
 
 import type { SessionNotification } from "@agentclientprotocol/sdk";
 
-import type { ServerMessage } from "../../daemon/message-protocol.js";
+import type { AssistantEvent } from "../../api/index.js";
 import { VellumAcpClientHandler } from "../client-handler.js";
 
 const ACP_SESSION_ID = "acp-session-abc";
@@ -10,9 +10,9 @@ const PARENT_CONVERSATION_ID = "conv-xyz";
 
 function makeHandler(): {
   handler: VellumAcpClientHandler;
-  sent: ServerMessage[];
+  sent: AssistantEvent[];
 } {
-  const sent: ServerMessage[] = [];
+  const sent: AssistantEvent[] = [];
   const handler = new VellumAcpClientHandler(
     ACP_SESSION_ID,
     (msg) => {

package/src/acp/__tests__/session-manager-persistence.test.ts

@@ -11,7 +11,7 @@
 import { beforeEach, describe, expect, test } from "bun:test";
 
 import type { AcpSessionUpdateEvent } from "../../api/events/acp-session-update.js";
-import type { ServerMessage } from "../../daemon/message-protocol.js";
+import type { AssistantEvent } from "../../api/index.js";
 import { getSqlite } from "../../persistence/db-connection.js";
 import { initializeDb } from "../../persistence/db-init.js";
 import { VellumAcpClientHandler } from "../client-handler.js";
@@ -47,8 +47,8 @@ function buildSessionWithFakeProcess(opts: {
   emitUpdate: (update: AcpSessionUpdateEvent) => void;
 } {
   const manager = new AcpSessionManager(1);
-  const sent: ServerMessage[] = [];
-  const sendToVellum = (msg: ServerMessage) => sent.push(msg);
+  const sent: AssistantEvent[] = [];
+  const sendToVellum = (msg: AssistantEvent) => sent.push(msg);
 
   type PromptResolution = {
     stopReason: string;
@@ -81,7 +81,7 @@ function buildSessionWithFakeProcess(opts: {
   ).eventBuffers;
   eventBuffers.set(opts.id, []);
 
-  const wrappedSend = (msg: ServerMessage) => {
+  const wrappedSend = (msg: AssistantEvent) => {
     if (msg.type === "acp_session_update") {
       (
         manager as unknown as {
@@ -464,7 +464,7 @@ describe("AcpSessionManager — terminal persistence", () => {
 
   test("emits acp_session_usage and persists input/output tokens from PromptResponse.usage", async () => {
     const id = "session-io-usage-1";
-    const sent: ServerMessage[] = [];
+    const sent: AssistantEvent[] = [];
     const handles = buildSessionWithFakeProcess({
       id,
       agentId: "agent-io",
@@ -478,11 +478,11 @@ describe("AcpSessionManager — terminal persistence", () => {
     // Capture the usage event emitted at turn end.
     const captureSend = (
       handles.manager as unknown as {
-        sessions: Map<string, { sendToVellum: (m: ServerMessage) => void }>;
+        sessions: Map<string, { sendToVellum: (m: AssistantEvent) => void }>;
       }
     ).sessions.get(id);
     const originalSend = captureSend!.sendToVellum;
-    captureSend!.sendToVellum = (msg: ServerMessage) => {
+    captureSend!.sendToVellum = (msg: AssistantEvent) => {
       sent.push(msg);
       originalSend(msg);
     };
@@ -515,7 +515,7 @@ describe("AcpSessionManager — terminal persistence", () => {
 
   test("does not emit usage or write token columns when PromptResponse carries no usage", async () => {
     const id = "session-io-no-usage-1";
-    const sent: ServerMessage[] = [];
+    const sent: AssistantEvent[] = [];
     const handles = buildSessionWithFakeProcess({
       id,
       agentId: "agent-io-none",
@@ -525,11 +525,11 @@ describe("AcpSessionManager — terminal persistence", () => {
 
     const entry = (
       handles.manager as unknown as {
-        sessions: Map<string, { sendToVellum: (m: ServerMessage) => void }>;
+        sessions: Map<string, { sendToVellum: (m: AssistantEvent) => void }>;
       }
     ).sessions.get(id);
     const originalSend = entry!.sendToVellum;
-    entry!.sendToVellum = (msg: ServerMessage) => {
+    entry!.sendToVellum = (msg: AssistantEvent) => {
       sent.push(msg);
       originalSend(msg);
     };

package/src/acp/__tests__/session-manager-resume.test.ts

@@ -208,7 +208,7 @@ const BUN_BIN = "/usr/local/bin/bun";
 const BUN_ADD_KEY = `${BUN_BIN} add`;
 
 import type { AcpSessionUpdateEvent } from "../../api/events/acp-session-update.js";
-import type { ServerMessage } from "../../daemon/message-protocol.js";
+import type { AssistantEvent } from "../../api/index.js";
 import { getSqlite } from "../../persistence/db-connection.js";
 import { initializeDb } from "../../persistence/db-init.js";
 import type { AcpSessionState } from "../types.js";
@@ -292,7 +292,7 @@ describe("AcpSessionManager.resumeFromHistory", () => {
     });
 
     const manager = new AcpSessionManager(4);
-    const sent: ServerMessage[] = [];
+    const sent: AssistantEvent[] = [];
     await manager.resumeFromHistory("resume-1", (msg) => sent.push(msg));
 
     const fake = fakeInstances[0]!;
@@ -355,7 +355,7 @@ describe("AcpSessionManager.resumeFromHistory", () => {
     });
 
     const manager = new AcpSessionManager(4);
-    const sent: ServerMessage[] = [];
+    const sent: AssistantEvent[] = [];
     await manager.resumeFromHistory("resume-seq-1", (msg) => sent.push(msg));
 
     const fake = fakeInstances[0]!;
@@ -716,7 +716,7 @@ describe("AcpSessionManager.resumeFromHistory", () => {
     insertHistoryRow({ id: "race-1" });
 
     const manager = new AcpSessionManager(4);
-    const sent: ServerMessage[] = [];
+    const sent: AssistantEvent[] = [];
     const [a, b] = await Promise.allSettled([
       manager.resumeFromHistory("race-1", (msg) => sent.push(msg)),
       manager.resumeFromHistory("race-1", (msg) => sent.push(msg)),
@@ -862,7 +862,7 @@ describe("AcpSessionManager.steerOrResume", () => {
     insertHistoryRow({ id: "sor-resume-1" });
 
     const manager = new AcpSessionManager(4);
-    const sent: ServerMessage[] = [];
+    const sent: AssistantEvent[] = [];
     const result = await manager.steerOrResume(
       "sor-resume-1",
       "continue the work",
@@ -904,7 +904,7 @@ describe("AcpSessionManager.steerOrResume", () => {
     insertHistoryRow({ id: "sor-race-1" });
 
     const manager = new AcpSessionManager(4);
-    const sent: ServerMessage[] = [];
+    const sent: AssistantEvent[] = [];
     const [a, b] = await Promise.all([
       manager.steerOrResume("sor-race-1", "first instruction", (msg) =>
         sent.push(msg),
@@ -943,7 +943,7 @@ describe("AcpSessionManager.steerOrResume", () => {
     });
 
     const manager = new AcpSessionManager(4);
-    const sent: ServerMessage[] = [];
+    const sent: AssistantEvent[] = [];
     const first = manager.steerOrResume(
       "sor-init-1",
       "first instruction",

package/src/acp/client-handler.ts

@@ -32,7 +32,7 @@ import type {
 } from "@agentclientprotocol/sdk";
 
 import type { AcpSessionUpdateEvent } from "../api/events/acp-session-update.js";
-import type { ServerMessage } from "../daemon/message-protocol.js";
+import type { AssistantEvent } from "../api/index.js";
 import { redactJsonStringLeaves } from "../security/redact-json.js";
 import { redactSensitiveFields } from "../security/redaction.js";
 import { redactSecrets } from "../security/secret-scanner.js";
@@ -72,7 +72,7 @@ interface TerminalState {
 
 /**
  * Vellum's ACP Client handler. Receives events from an ACP agent and
- * forwards them as ServerMessage objects to connected Vellum clients.
+ * forwards them as AssistantEvent objects to connected Vellum clients.
  */
 export class VellumAcpClientHandler implements Client {
   private terminals = new Map<string, TerminalState>();
@@ -101,7 +101,7 @@ export class VellumAcpClientHandler implements Client {
 
   constructor(
     private readonly acpSessionId: string,
-    private readonly sendToVellum: (msg: ServerMessage) => void,
+    private readonly sendToVellum: (msg: AssistantEvent) => void,
     private readonly parentConversationId: string,
   ) {}
 

package/src/acp/session-manager.ts

@@ -9,8 +9,8 @@ import { basename } from "node:path";
 import { eq, inArray } from "drizzle-orm";
 
 import type { AcpSessionUpdateEvent } from "../api/events/acp-session-update.js";
+import type { AssistantEvent } from "../api/index.js";
 import { findConversation } from "../daemon/conversation-registry.js";
-import type { ServerMessage } from "../daemon/message-protocol.js";
 import { getDb } from "../persistence/db-connection.js";
 import { acpSessionHistory } from "../persistence/schema/index.js";
 import * as pendingInteractions from "../runtime/pending-interactions.js";
@@ -69,7 +69,7 @@ interface SessionEntry {
   state: AcpSessionState;
   clientHandler: VellumAcpClientHandler;
   /** Wrapped sender that also appends to the ring buffer. */
-  sendToVellum: (msg: ServerMessage) => void;
+  sendToVellum: (msg: AssistantEvent) => void;
   currentPrompt: Promise<unknown> | null;
   parentConversationId: string;
   cwd: string;
@@ -195,7 +195,7 @@ export class AcpSessionManager {
     task: string,
     cwd: string,
     parentConversationId: string,
-    sendToVellum: (msg: ServerMessage) => void,
+    sendToVellum: (msg: AssistantEvent) => void,
     parentToolUseId?: string,
   ): Promise<{ acpSessionId: string; protocolSessionId: string }> {
     this.assertCapacity();
@@ -275,7 +275,7 @@ export class AcpSessionManager {
     parentConversationId: string;
     cwd: string;
     startedAt: number;
-    sendToVellum: (msg: ServerMessage) => void;
+    sendToVellum: (msg: AssistantEvent) => void;
     parentToolUseId?: string;
     task?: string;
   }): SessionEntry {
@@ -287,7 +287,7 @@ export class AcpSessionManager {
     // Wrap the sender so every emitted message is mirrored into the buffer
     // when it's an `acp_session_update`. The wrapper preserves the original
     // call semantics: it forwards every message unchanged.
-    const wrappedSend = (msg: ServerMessage) => {
+    const wrappedSend = (msg: AssistantEvent) => {
       if (msg.type === "acp_session_update") {
         this.appendToBuffer(acpSessionId, msg);
       } else if (msg.type === "acp_session_usage") {
@@ -383,7 +383,7 @@ export class AcpSessionManager {
    */
   async resumeFromHistory(
     acpSessionId: string,
-    sendToVellum: (msg: ServerMessage) => void,
+    sendToVellum: (msg: AssistantEvent) => void,
   ): Promise<void> {
     if (
       this.sessions.has(acpSessionId) ||
@@ -448,7 +448,7 @@ export class AcpSessionManager {
   private async performResume(
     acpSessionId: string,
     row: ResumableHistoryRow,
-    sendToVellum: (msg: ServerMessage) => void,
+    sendToVellum: (msg: AssistantEvent) => void,
   ): Promise<void> {
     // Resolve the adapter, silently auto-installing a missing allowlisted
     // binary via the same sandboxed `bun` path as spawn (see
@@ -658,7 +658,7 @@ export class AcpSessionManager {
   async steerOrResume(
     acpSessionId: string,
     instruction: string,
-    sendToVellum: (msg: ServerMessage) => void,
+    sendToVellum: (msg: AssistantEvent) => void,
   ): Promise<{ resumed: boolean }> {
     try {
       await this.steer(acpSessionId, instruction);

package/src/api/events/subagent-event.ts

@@ -1,7 +1,7 @@
 /**
  * `subagent_event` SSE event.
  *
- * Server → client envelope wrapping any inner `ServerMessage`
+ * Server → client envelope wrapping any inner `AssistantEvent`
  * emitted by a subagent's conversation. The daemon's subagent
  * manager rebroadcasts the subagent's own stream through the
  * parent conversation's `sendToClient`, tagged with the subagent's
@@ -9,7 +9,7 @@
  * to route inner events to the appropriate inline subagent surface.
  *
  * The inner `event` is opaque on the wire — it is itself a fully
- * structured `ServerMessage` (any member of the canonical event
+ * structured `AssistantEvent` (any member of the canonical event
  * union) and re-validating it here would duplicate work and
  * tightly couple subagent canonicalization to every other event
  * schema. Clients re-parse `event` through the same event parser

package/src/api/responses/memory-v2-activation-log.ts

@@ -2,7 +2,7 @@
  * Wire contract for the memory v2 activation log surfaced in the
  * inspector's Memory tab. Mirrors the return value of
  * `getMemoryV2ActivationLogByMessageIds` in
- * `assistant/src/memory/memory-v2-activation-log-store.ts`.
+ * `assistant/src/plugins/defaults/memory/v2/activation-log-store.ts`.
  *
  * Canonical wire-contract source. Assistant code imports the types
  * directly from this file via relative paths; external consumers
@@ -20,7 +20,7 @@ import { z } from "zod";
 /**
  * One concept row in the V2 activation log. Mirrors
  * `MemoryV2ConceptRowRecord` from
- * `assistant/src/memory/memory-v2-activation-log-store.ts`.
+ * `assistant/src/plugins/defaults/memory/v2/activation-log-store.ts`.
  *
  * `source` and `status` are open-ended strings on the wire — the
  * daemon emits known values like `prior_state`, `ann_top50`, `both`

package/src/approvals/AGENTS.md

@@ -1,5 +1,7 @@
 # Approvals & Guardian Rules
 
+The end-to-end lifecycle of interactive guardian requests (approvals, questions) — promotion, notification cards, reply routing, resolution — is mapped in [docs/guardian-request-flow.md](../../docs/guardian-request-flow.md). Read it before extending any decision or card-delivery path.
+
 ## Approval Flow Resilience
 
 - **Rich delivery failures must degrade gracefully.** If delivering a rich approval prompt (e.g., Telegram inline buttons) fails, fall back to plain text with instructions (e.g., `Reply "yes" to approve`) — never auto-deny.

package/src/approvals/guardian-request-resolvers.ts

@@ -26,6 +26,7 @@ import { getGuardianRequestOrNull } from "../channels/gateway-guardian-requests.
 import { findContactChannel } from "../contacts/contact-store.js";
 import { findConversation } from "../daemon/conversation-registry.js";
 import { emitNotificationSignal } from "../notifications/emit-signal.js";
+import { parseQuestionAnswerActionId } from "../notifications/guardian-question-mode.js";
 import {
   isNotificationSourceChannel,
   type NotificationSourceChannel,
@@ -34,6 +35,7 @@ import type {
   TrustedContactDecisionPayload,
   TrustedContactVerificationSentPayload,
 } from "../notifications/trusted-contact-payloads.js";
+import type { QuestionBatchSubmission } from "../permissions/question-prompter.js";
 import type { UserDecision } from "../permissions/types.js";
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "../runtime/assistant-scope.js";
 import {
@@ -48,6 +50,10 @@ import {
   resolveTrustBinding,
 } from "../runtime/introduction-policy.js";
 import * as pendingInteractions from "../runtime/pending-interactions.js";
+import {
+  readBatchMetadata,
+  resolvePendingQuestion,
+} from "../runtime/question-resolution.js";
 import { TC_GRANT_WAIT_MAX_MS } from "../tools/tool-approval-handler.js";
 import { getLogger } from "../util/logger.js";
 import { resolveDeliverCallbackUrlForChannel } from "./guardian-channel-delivery.js";
@@ -409,11 +415,16 @@ const pendingInteractionResolver: GuardianRequestResolver = {
 };
 
 /**
- * Resolves `pending_question` requests — the voice call question path.
+ * Resolves `pending_question` requests. Two variants share the kind,
+ * distinguished by provenance fields:
+ *
+ *  - Voice-call questions carry a `callSessionId` (+ `pendingQuestionId`);
+ *    the answer is delivered to the live call session via `answerCall`.
+ *  - `ask_question` prompts carry neither — the request id IS the pending
+ *    `question` interaction's requestId (mirroring `tool_approval` rows), and
+ *    the answer resolves that interaction so the parked tool call returns.
  *
- * Validates that voice-specific fields (callSessionId, pendingQuestionId)
- * are present and delivers the answer to the live call session. An
- * `answerCall` failure surfaces as `resolverFailed` — the committed decision
+ * Side-effect failures surface as `resolverFailed` — the committed decision
  * stands (no reopen).
  */
 const pendingQuestionResolver: GuardianRequestResolver = {
@@ -423,10 +434,7 @@ const pendingQuestionResolver: GuardianRequestResolver = {
     const { request, decision, actor: _actor } = ctx;
 
     if (!request.callSessionId) {
-      return {
-        ok: false,
-        reason: "pending_question request missing callSessionId",
-      };
+      return resolveAskQuestionInteraction(request, decision);
     }
 
     if (!request.pendingQuestionId) {
@@ -487,6 +495,100 @@ const pendingQuestionResolver: GuardianRequestResolver = {
   },
 };
 
+/**
+ * Resolve an `ask_question` pending interaction from a guardian decision.
+ *
+ * The decision's `userText` carries either an answer-option token
+ * (`answer_<idx>` / `answer_skip`, from a tapped card button — see
+ * {@link parseQuestionAnswerActionId}) or the guardian's free-typed answer.
+ * A reject decision with no text is an explicit skip. Submission validation
+ * and the prompter hand-off go through the shared
+ * {@link resolvePendingQuestion}, the same core `/v1/question-response` uses,
+ * so an app-card answer and a channel answer resolve identically.
+ */
+async function resolveAskQuestionInteraction(
+  request: GuardianRequestWire,
+  decision: ResolverDecision,
+): Promise<ResolverResult> {
+  const interaction = pendingInteractions.get(request.id);
+  if (!interaction || interaction.kind !== "question") {
+    // The parked prompt is gone (answered elsewhere, timed out, or the daemon
+    // restarted). The committed decision stands; there is just nothing left to
+    // resume.
+    return { ok: false, reason: "no_pending_question_interaction" };
+  }
+
+  const { orderedIds, optionsById } = readBatchMetadata(interaction);
+  if (orderedIds.length !== 1) {
+    // Channel cards are only created for single-question batches (the
+    // promotion gate enforces it); a multi-question interaction cannot be
+    // answered by one decision.
+    return { ok: false, reason: "question_batch_not_single" };
+  }
+  const questionId = orderedIds[0]!;
+
+  let submission: QuestionBatchSubmission;
+  const answerSelection = decision.userText
+    ? parseQuestionAnswerActionId(decision.userText.trim())
+    : null;
+  if (answerSelection?.kind === "skip") {
+    submission = { questionId, kind: "skip" };
+  } else if (answerSelection?.kind === "option") {
+    const optionId = (optionsById[questionId] ?? [])[answerSelection.index];
+    if (!optionId) {
+      return { ok: false, reason: "question_option_index_out_of_range" };
+    }
+    submission = { questionId, kind: "option", optionId };
+  } else if (decision.userText && decision.userText.trim().length > 0) {
+    submission = {
+      questionId,
+      kind: "free_text",
+      text: decision.userText.trim(),
+    };
+  } else if (DENYING_ACTION_SET.has(decision.action)) {
+    submission = { questionId, kind: "skip" };
+  } else {
+    // Bare approval with no text (e.g. "CODE approve") — affirm without
+    // inventing content; the model reads the affirmation in context.
+    submission = { questionId, kind: "free_text", text: "Yes" };
+  }
+
+  const outcome = resolvePendingQuestion(request.id, {
+    kind: "submit",
+    submissions: [submission],
+  });
+  if (outcome.status !== "resolved") {
+    log.warn(
+      {
+        event: "resolver_ask_question_not_resolved",
+        requestId: request.id,
+        outcome: outcome.status,
+        ...(outcome.status === "invalid" ? { message: outcome.message } : {}),
+      },
+      "Ask-question resolver: pending interaction did not resolve",
+    );
+    return {
+      ok: false,
+      reason:
+        outcome.status === "invalid"
+          ? "question_submission_invalid"
+          : "no_pending_question_interaction",
+    };
+  }
+
+  log.info(
+    {
+      event: "resolver_ask_question_applied",
+      requestId: request.id,
+      action: decision.action,
+      submissionKind: submission.kind,
+      conversationId: outcome.conversationId,
+    },
+    "Ask-question resolver: pending interaction resolved",
+  );
+  return { ok: true, applied: true };
+}
+
 /**
  * The four introduction-card outcomes for an access request. The generic
  * decision pair maps onto them: `approve_once` → `verify_code` (handshake),
@@ -658,9 +760,9 @@ async function deliverRequesterNotice(params: {
 }
 
 /**
- * Emit the guardian-facing denial lifecycle signals and, unless suppressed,
+ * Emit the guardian-facing denial lifecycle signal and, unless suppressed,
  * deliver the "declined" notice to the requester. Both the `leave_unverified`
- * and `block` outcomes call this for the lifecycle signals, but the requester
+ * and `block` outcomes call this for the lifecycle signal, but the requester
  * notice is delivered only for `block` (in denied mode) — `leave_unverified`
  * always passes `suppressRequesterNotice: true`, staying a silent park at
  * `unverified`. The notice text is a plain decline that does not reveal whether
@@ -712,6 +814,12 @@ async function notifyRequesterOfDenial(params: {
     });
   }
 
+  // Exactly one signal per denial: the payload's `decision: "denied"`
+  // carries the verdict, and the pipeline can only dedupe within a single
+  // event stream — a second event name would materialize a second
+  // conversation for the same decision. The approve path holds the same
+  // one-signal invariant via `verification_sent` standing in for
+  // `guardian_decision`.
   if (channelDeliveryContext) {
     void emitNotificationSignal({
       sourceEventName: "ingress.trusted_contact.guardian_decision",
@@ -726,20 +834,6 @@ async function notifyRequesterOfDenial(params: {
       contextPayload: deniedPayload,
       dedupeKey: `trusted-contact:guardian-decision:${requestId}`,
     });
-
-    void emitNotificationSignal({
-      sourceEventName: "ingress.trusted_contact.denied",
-      sourceChannel: channel,
-      sourceContextId: conversationId ?? "",
-      attentionHints: {
-        requiresAction: false,
-        urgency: "low",
-        isAsyncBackground: false,
-        visibleInSourceNow: false,
-      },
-      contextPayload: deniedPayload,
-      dedupeKey: `trusted-contact:denied:${requestId}`,
-    });
   }
 }
 

package/src/calls/__tests__/voice-control-protocol.test.ts

@@ -4,6 +4,8 @@ import {
   couldBeControlMarker,
   ESCALATE_VERDICT_TOKEN,
   HOLD_VERDICT_TOKEN,
+  isIncompleteControlMarkerTail,
+  MINIMIZE_ROOM_MARKER,
   stripInternalSpeechMarkers,
 } from "../voice-control-protocol.js";
 
@@ -46,3 +48,58 @@ describe("front-door verdict tokens", () => {
     );
   });
 });
+
+describe("minimize-room marker", () => {
+  test("marker constant is the expected bracketed form", () => {
+    expect(MINIMIZE_ROOM_MARKER).toBe("[-1]");
+  });
+
+  test("stripInternalSpeechMarkers removes the marker so it is never spoken", () => {
+    expect(
+      stripInternalSpeechMarkers("Done [-1] here").replace(/\s+/g, " "),
+    ).toBe("Done here");
+  });
+
+  test("couldBeControlMarker holds the marker and its streaming prefixes", () => {
+    for (const text of ["[", "[-", "[-1", "[-1]", "[-1] trailing"]) {
+      expect(couldBeControlMarker(text)).toBe(true);
+    }
+  });
+
+  test("a bracket prefix that disproves the marker is not held", () => {
+    expect(couldBeControlMarker("[- something else")).toBe(false);
+  });
+});
+
+describe("isIncompleteControlMarkerTail", () => {
+  test("strict prefixes of any marker are incomplete", () => {
+    for (const tail of ["[", "[-", "[-1", "[END_CAL", "[ASK_GUARDIAN_APPRO"]) {
+      expect(isIncompleteControlMarkerTail(tail)).toBe(true);
+    }
+  });
+
+  test("complete literal markers are not held", () => {
+    for (const tail of ["[-1]", "[END_CALL]", "[0] answer", "[-1] look here"]) {
+      expect(isIncompleteControlMarkerTail(tail)).toBe(false);
+    }
+  });
+
+  test("guardian-approval is judged by the balanced parser, not the first bracket", () => {
+    const streaming =
+      '[ASK_GUARDIAN_APPROVAL: {"question": "ok]?", "options": ["a", "b"';
+    expect(isIncompleteControlMarkerTail(streaming)).toBe(true);
+    expect(isIncompleteControlMarkerTail(`${streaming}]}]`)).toBe(false);
+  });
+
+  test("colon-style markers terminate at their first bracket", () => {
+    expect(isIncompleteControlMarkerTail("[ASK_GUARDIAN: may I")).toBe(true);
+    expect(isIncompleteControlMarkerTail("[ASK_GUARDIAN: may I?]")).toBe(false);
+    expect(isIncompleteControlMarkerTail("[USER_ANSWERED: yes")).toBe(true);
+  });
+
+  test("non-marker bracket text is not held", () => {
+    for (const tail of ["[- something else", "[sic]", '["a", "b"]']) {
+      expect(isIncompleteControlMarkerTail(tail)).toBe(false);
+    }
+  });
+});