@oar-sh/oar 0.9.2 → 0.9.4

package/server/claude-worker/claude-session-worker.mjs

@@ -18,6 +18,7 @@ import { resolveDeliveredAutoCompactWindow } from '../../shared/auto-compact-win
 import { resolveDeliveredThinking } from '../../shared/claude-thinking.mjs';
 import { installWorkerCrashGuard } from '../../shared/worker-crash-guard.mjs';
 import { createClaudeSessionRunner } from './claude-session-process.mjs';
+import { createRunnerLinkBridge, failSettlingRowsOnShutdown } from './claude-worker-link-wiring.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const HEARTBEAT_MS = 10_000;
@@ -82,6 +83,9 @@ async function main() {
     onAbortSubagent: (subagentRunId) => turnRunner.stopBackgroundTaskByToolUseId(subagentRunId),
     dbg,
   });
+  const linkBridge = createRunnerLinkBridge();
+  // Late-bound: the heartbeat controller is built after the runner.
+  let heartbeat = null;
   const turnRunner = createClaudeSessionRunner({
     api,
     sdkSessionId,
@@ -102,11 +106,19 @@ async function main() {
     getBackgroundTaskTimeoutMs: () => backgroundTaskTimeoutMs,
     getAutoCompactWindow: () => autoCompactWindow,
     getThinking: () => thinking,
+    // A readiness flip is a hold starting or ending (question card,
+    // compaction, a turn-opening delivery): the steering snapshot changed
+    // with it, so it goes out now rather than on the next 10 s heartbeat.
+    onDeliveryReadinessChange: (ready) => {
+      linkBridge.onDeliveryReadinessChange(ready);
+      heartbeat?.requestPulse();
+    },
+    canHandBackHeldDelivery: () => linkBridge.canHandBackHeldDelivery(),
     dbg,
   });
 
   let heartbeatTimer = null;
-  const heartbeat = createHeartbeatController({
+  heartbeat = createHeartbeatController({
     api,
     pollMs: HEARTBEAT_MS,
     getSessionReady: () => true,
@@ -118,6 +130,13 @@ async function main() {
     // the crash guard below takes the entries whole so its requeues stay
     // fenced to this attempt.
     getActiveQueueMessageIds: () => turnRunner.getActiveQueueMessageIds().map((entry) => entry.id),
+    // Composer steering snapshot. Holds reach the relay within a pulse window
+    // (onDeliveryReadinessChange above) and a relay that just came up gets it
+    // on its first hello; the periodic beat only backstops the rest.
+    getSteeringState: () => turnRunner.steeringState(),
+    // Consumed rows the runner could not fail itself; the relay fails them.
+    getSettleFailed: () => turnRunner.getSettleFailed(),
+    onSettleFailedHandled: (ids) => turnRunner.acknowledgeSettleFailed(ids),
   });
 
   const wsLink = createWorkerWebSocketLink({
@@ -125,6 +144,18 @@ async function main() {
     token,
     dbg,
     getSessionReady: () => true,
+    // Mid-turn steering: while a turn is running and the runner can absorb
+    // another message into it, the link keeps signalling readiness, so a
+    // message sent while Claude is thinking is pushed into the live turn
+    // instead of waiting for the result (docs/plans/2026-09-19-claude-mid-
+    // turn-steering.md).
+    getSteeringReady: () => turnRunner.canAcceptSteering(),
+    // A hold (open question card, compaction, adoption) suppresses readiness
+    // even between deliveries — a delivery drawn into it is only handed back.
+    getDeliveryHeld: () => turnRunner.isDeliveryHeld(),
+    // A relay that just (re)started knows nothing of this worker until it
+    // heartbeats; the composer's steering snapshot rides that beat.
+    onServerHello: () => heartbeat.requestPulse(),
     getSessionId: () => sdkSessionId,
     getPid: () => process.pid,
     onDeliver: async (pending, reason) => {
@@ -158,20 +189,30 @@ async function main() {
       dbg('unknown worker control ignored', type || '(none)');
     },
   });
+  linkBridge.attach(wsLink);
 
-  const shutdown = (signal) => {
+  let shuttingDown = false;
+  const shutdown = async (signal) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
     dbg(`shutting down (${signal})`);
     try { wsLink.stop(); } catch {}
     try { heartbeat.stopHeartbeat(); } catch {}
     try { controlPoller.stop(); } catch {}
+    // Consumed steers still settling must fail, not be left for dead-worker
+    // recovery to requeue and run twice (same 2 s cap as the crash guard).
+    try {
+      const failed = await failSettlingRowsOnShutdown({ api, runner: turnRunner, timeoutMs: 2_000 });
+      if (failed) dbg(`failed ${failed} settling row(s) before exit`);
+    } catch {}
     // Hard-close the persistent CLI process; a worker teardown cannot save
     // its background tasks, and the orphan-notification replay on the next
     // resume reports whatever they left behind.
     try { turnRunner.shutdown({ graceful: false }); } catch {}
     process.exit(0);
   };
-  process.on('SIGTERM', () => shutdown('SIGTERM'));
-  process.on('SIGINT', () => shutdown('SIGINT'));
+  process.on('SIGTERM', () => { void shutdown('SIGTERM'); });
+  process.on('SIGINT', () => { void shutdown('SIGINT'); });
   installWorkerCrashGuard({
     api,
     workerName: 'claude-session-worker',

package/server/claude-worker/claude-turn-publisher.mjs

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import { countPlanLikeLines } from '../../shared/plan-lines.mjs';
 import { EMPTY_TURN_COMPLETION_NOTE } from '../../shared/empty-turn-completion.mjs';
+import { buildSteerSettleFailure, steerSettleFailureText } from '../../shared/steer-settle-failure.mjs';
 
 const PLAN_BOARD_ACTIONS = [
   { id: 'autopilot', label: 'Implement in autopilot', mode: 'autopilot' },
@@ -25,6 +26,9 @@ export function isStaleAttemptError(error) {
   return detail.includes('stale_attempt');
 }
 
+export { buildSteerSettleFailure, steerSettleFailureText };
+export const STEER_SETTLE_FAILED_TEXT = steerSettleFailureText('folded');
+
 export function buildClaudePlanReadyBoardPayload({ message, planText = '' } = {}) {
   const summary = String(planText || '').trim();
   if (!summary) return null;
@@ -55,6 +59,11 @@ export function buildClaudePlanReadyBoardPayload({ message, planText = '' } = {}
  * (delivered or background-continuation) through one publisher.
  */
 export function createClaudeTurnPublisher({ api, dbg = () => {}, takeWorkflowRuns = null } = {}) {
+  function drainWorkflowRuns({ terminal = false } = {}) {
+    if (terminal || typeof takeWorkflowRuns !== 'function') return null;
+    return takeWorkflowRuns();
+  }
+
   async function postActivity(message, text, subagentRunId = null, metadata = null) {
     if (!text) return;
     await api('POST', '/api/activity', {
@@ -180,36 +189,86 @@ export function createClaudeTurnPublisher({ api, dbg = () => {}, takeWorkflowRun
     }).catch(() => {});
   }
 
-  async function publishResponse(message, { text, model, terminalError = null, modelOrigin }) {
+  /**
+   * Returns the outcome: 'published' (the relay took it), 'stale' (another
+   * attempt owns the row), 'failed' (not taken and NOT requeued), or
+   * 'requeued'. A `kind` marks a row whose prompt the CLI already consumed —
+   * 'absorbed' (the reply continues through the next, steered message),
+   * 'folded' (answered by the turn it was steered into) or 'stopped' (steered
+   * into a turn the user stopped) — and such a row is never
+   * requeued, since re-delivery would run the prompt a second time; the
+   * caller owns retrying it. `requeueOnFailure: false` opts any other publish
+   * into the same contract.
+   */
+  async function publishResponse(message, {
+    text,
+    model,
+    terminalError = null,
+    modelOrigin,
+    absorbed = false,
+    kind = null,
+    requeueOnFailure = true,
+    // Ids of steered queue rows pushed into the turn this response finishes
+    // and still unsettled: the relay marks them consumed in the same
+    // transaction, so no recovery path ever re-runs them (at-most-once even
+    // if this worker dies before settling them).
+    consumedSteerIds = null,
+    // A caller retrying one publish drains the settled workflow digests ONCE
+    // and passes them to every attempt, so a failed attempt cannot lose them.
+    workflowRuns: presetWorkflowRuns,
+  }) {
+    const responseKind = kind || (absorbed ? 'absorbed' : null);
     // Final digests of workflows that settled since the last response ride the
     // next successful response publish — the summarizing turn is the natural
     // transcript anchor for the "Finished background task" card. Terminal
     // failures skip the drain so the digests stay buffered for a later turn;
     // if this POST fails (→ requeue) or the process dies before any response
     // publishes, the drained digests are lost — acceptable v1.
-    const workflowRuns = (!terminalError && typeof takeWorkflowRuns === 'function')
-      ? takeWorkflowRuns()
-      : null;
-    await api('POST', '/api/response', {
-      messageId: message.id,
-      conversationId: message.conversationId,
-      text: String(text || ''),
-      model: model || null,
-      modelOrigin: modelOrigin
-        || (String(message?.model || '').trim().toLowerCase() === 'auto' ? 'auto' : 'manual'),
-      ...(Array.isArray(workflowRuns) && workflowRuns.length ? { workflowRuns } : {}),
-      ...(terminalError ? { terminalError } : {}),
-      ...attemptFields(message),
-    }).catch(async (error) => {
+    const workflowRuns = presetWorkflowRuns !== undefined
+      ? presetWorkflowRuns
+      : drainWorkflowRuns({ terminal: Boolean(terminalError) });
+    // Entries are { id, attemptId } (the relay fences each mark on its
+    // attempt) or bare ids.
+    const consumed = (Array.isArray(consumedSteerIds) ? consumedSteerIds : [])
+      .map((entry) => (entry && typeof entry === 'object'
+        ? { id: String(entry.id || '').trim(), attemptId: entry.attemptId || null }
+        : { id: String(entry || '').trim(), attemptId: null }))
+      .filter((entry) => entry.id);
+    try {
+      await api('POST', '/api/response', {
+        messageId: message.id,
+        conversationId: message.conversationId,
+        text: String(text || ''),
+        model: model || null,
+        modelOrigin: modelOrigin
+          || (String(message?.model || '').trim().toLowerCase() === 'auto' ? 'auto' : 'manual'),
+        ...(Array.isArray(workflowRuns) && workflowRuns.length ? { workflowRuns } : {}),
+        ...(terminalError ? { terminalError } : {}),
+        // The relay stamps the assistant message's kind from these: 'absorbed'
+        // renders as merged into the next (steered) user message, 'folded' as
+        // a compact marker on its own message, 'stopped' as a steer the
+        // user's Stop cut off unanswered.
+        ...(responseKind === 'absorbed' ? { absorbed: true } : {}),
+        ...(responseKind && responseKind !== 'absorbed' ? { kind: responseKind } : {}),
+        ...(consumed.length ? { consumedSteerIds: consumed } : {}),
+        ...attemptFields(message),
+      });
+      return 'published';
+    } catch (error) {
       // A stale_attempt 409 means the row already moved on to another attempt
       // (requeued and re-delivered); the requeue would 409 the same way, and
       // the newer attempt owes the row its answer — drop this one.
       if (isStaleAttemptError(error)) {
         dbg('response refused as stale_attempt; dropping', message.id);
-        return;
+        return 'stale';
+      }
+      if (responseKind || !requeueOnFailure) {
+        dbg('response publish failed; not requeuing a consumed prompt', message.id, error?.message || String(error));
+        return 'failed';
       }
       await api('POST', '/api/requeue', { messageId: message.id, ...attemptFields(message) }).catch(() => {});
-    });
+      return 'requeued';
+    }
   }
 
   /**
@@ -244,7 +303,7 @@ export function createClaudeTurnPublisher({ api, dbg = () => {}, takeWorkflowRun
    * plan-mode fallback board, response row. Mirrors the pre-session-process
    * turn runner's tail exactly.
    */
-  async function publishCompletedTurn({ message, state, responseModel, planBoardPosted }) {
+  async function publishCompletedTurn({ message, state, responseModel, planBoardPosted, consumedSteerIds = null }) {
     const result = state.result;
     const finalText = String(
       state.resultTexts.join('\n\n') || result?.text || state.lastStreamedText || '',
@@ -266,10 +325,10 @@ export function createClaudeTurnPublisher({ api, dbg = () => {}, takeWorkflowRun
     // fails the message with a misleading "Relay timeout".
     const publishedText = finalText || EMPTY_TURN_COMPLETION_NOTE;
     await publishFinalStream(message, publishedText);
-    await publishResponse(message, { text: publishedText, model: responseModel });
+    await publishResponse(message, { text: publishedText, model: responseModel, consumedSteerIds });
   }
 
-  async function publishErrorResult({ message, state, responseModel }) {
+  async function publishErrorResult({ message, state, responseModel, consumedSteerIds = null }) {
     const result = state.result;
     const errorText = result.text
       || `Claude turn failed (${result.subtype || 'unknown error'}).`;
@@ -285,6 +344,7 @@ export function createClaudeTurnPublisher({ api, dbg = () => {}, takeWorkflowRun
         failedAt: new Date().toISOString(),
         queueMessageId: String(message.id || '') || null,
       },
+      consumedSteerIds,
     });
   }
 
@@ -308,6 +368,7 @@ export function createClaudeTurnPublisher({ api, dbg = () => {}, takeWorkflowRun
 
   return {
     postActivity,
+    drainWorkflowRuns,
     dispatchAction,
     publishContextUsage,
     publishPlanUsage,

package/server/claude-worker/claude-worker-link-wiring.mjs

@@ -0,0 +1,9 @@
+// The Claude worker's glue between its session runner and the relay socket
+// link. The implementation moved to shared/worker-runtime/runner-link-wiring.mjs
+// when the Copilot SDK worker adopted the same delivery gate; this module is
+// the import path the Claude worker and its tests still use.
+
+export {
+  createRunnerLinkBridge,
+  failSettlingRowsOnShutdown,
+} from '../../shared/worker-runtime/runner-link-wiring.mjs';

package/server/claude-worker/sdk-message-normalizer.mjs

@@ -1,5 +1,6 @@
 import { capThought } from '../../shared/thought-cap.mjs';
 import { shouldEmitStreamUpdate } from '../../shared/stream-emit-gating.mjs';
+import { isRemoteRelayToolName, remoteRelayActivitySummary } from '../../shared/remote-relay-tool-core.mjs';
 
 const MAX_TOOL_DETAIL_LENGTH = 140;
 const REDACTED_THINKING_PLACEHOLDER = '[Reasoning redacted by the model provider]';
@@ -89,6 +90,12 @@ export function isSubagentToolName(name) {
 
 export function summarizeToolInput(toolName, input) {
   if (!input || typeof input !== 'object') return '';
+  // `mcp__relay__remote_relay` reads as what it does on which relay
+  // (`send → linux-test session 01234567: “…”`), not as its first argument.
+  if (isRemoteRelayToolName(toolName)) {
+    const summary = remoteRelayActivitySummary(input);
+    if (summary) return summary;
+  }
   const candidates = [
     input.command,
     input.file_path,

package/server/copilot-worker/copilot-ask-user-tool.mjs

@@ -0,0 +1,89 @@
+// The relay's own `ask_user` tool for Copilot SDK sessions.
+//
+// The runtime's built-in `ask_user` offers the model only `question` and
+// `choices` (captured from the request body, runtime 1.0.88), so a model has
+// no way to say "the user may pick several of these" — and the relay could
+// only guess from the wording. The SDK lets a host register a tool that
+// overrides a built-in one of the same name (`overridesBuiltInTool`), so the
+// worker registers this superset instead: the same name and fields every
+// model already knows, plus `multi_select`. Verified with the fake-provider
+// probe (2026-09-25): the model sees exactly one `ask_user` with this schema,
+// the handler receives the call, and the built-in path is never used.
+//
+// Pure: schema, argument parsing and the result wording. The session process
+// wires the handler to the relay question bridge.
+
+import { normalizeUserInputChoices } from './copilot-question-bridge.mjs';
+
+export const RELAY_ASK_USER_TOOL_NAME = 'ask_user';
+
+export const RELAY_ASK_USER_TOOL_DESCRIPTION = [
+  'Ask the user a question and wait for their response.',
+  'Use this tool when you need to ask the user questions during execution. This allows you to:',
+  '1. Gather user preferences or requirements',
+  '2. Clarify ambiguous instructions',
+  '3. Get decisions on implementation choices as you work',
+  '4. Offer choices to the user about what direction to take',
+  'The question is shown to the user as a card with a button per choice.',
+  'Set multi_select to true when the user may pick several of the choices (the choices are not',
+  'mutually exclusive); the answer then lists every pick, separated by ", ". Leave it false or',
+  'omit it when exactly one choice applies.',
+].join('\n');
+
+export const RELAY_ASK_USER_TOOL_PARAMETERS = Object.freeze({
+  type: 'object',
+  properties: {
+    question: {
+      type: 'string',
+      description: 'The question to ask the user. Ensure only one question is asked at a time - do not bundle multiple questions together.',
+    },
+    choices: {
+      type: 'array',
+      items: { type: 'string' },
+      description: 'Optional list of choices for a multiple choice question. Prefer providing choices when possible.',
+    },
+    multi_select: {
+      type: 'boolean',
+      description: 'true when the user may pick several of the choices; false or omitted when exactly one applies.',
+    },
+  },
+  required: ['question'],
+});
+
+/** The call's arguments, tolerating the camelCase spelling some models emit. */
+export function parseAskUserToolArguments(args) {
+  const source = args && typeof args === 'object' && !Array.isArray(args) ? args : {};
+  return {
+    question: String(source.question || '').trim(),
+    choices: normalizeUserInputChoices(source.choices),
+    multiSelect: source.multi_select === true || source.multiSelect === true,
+  };
+}
+
+/**
+ * The tool result the model reads, worded like the built-in's ("User
+ * selected: b" for a choice, "User responded: …" for anything else) so a
+ * model's habits carry over. A timed-out card returns the bridge's
+ * continuation text as it is.
+ */
+export function formatAskUserToolResult({ answer, wasFreeform = true, timedOut = false } = {}) {
+  const text = String(answer ?? '').trim();
+  if (timedOut) return text;
+  if (!text) return 'User responded with an empty answer.';
+  // `wasFreeform` comes from the question bridge (`deriveWasFreeform`), the
+  // single owner of "was this one of the offered choices".
+  return wasFreeform === false ? `User selected: ${text}` : `User responded: ${text}`;
+}
+
+/**
+ * Whether a session create/resume failure is the runtime refusing the
+ * override (an older runtime without `overridesBuiltInTool`, or one that
+ * rejects replacing this built-in). Anything else is a real failure.
+ */
+export function isToolOverrideRejection(error) {
+  const message = String(error?.message || error || '');
+  if (/overridesBuiltInTool/i.test(message)) return true;
+  // The tool named together with an override/clash complaint — a message that
+  // merely mentions ask_user (a replayed call in history, say) is not one.
+  return /\bask_user\b/i.test(message) && /(built-?in|clash|conflict|overrid|duplicate)/i.test(message);
+}

package/server/copilot-worker/copilot-continuation-signals.mjs

@@ -54,6 +54,51 @@ export const SHELL_SETTLED_NOTIFICATION_KINDS = Object.freeze([
 /** Tools that address an already-running shell by id. */
 export const SHELL_HANDLE_TOOLS = Object.freeze(['read_bash', 'write_bash', 'stop_bash']);
 
+/**
+ * `system.notification` kinds that mean "a background agent this session
+ * started is done" — `agent_idle` for a multi-turn agent that finished its
+ * prompt and now waits for messages, `agent_completed` for a single-shot one.
+ * Both make the runtime re-invoke the model (`read_agent` + a reply under the
+ * spawning interaction), so both herald a continuation exactly like the shell
+ * kinds do (live-probed on runtime 1.0.88, 2026-09-25).
+ */
+export const AGENT_SETTLED_NOTIFICATION_KINDS = Object.freeze([
+  'agent_completed',
+  'agent_idle',
+]);
+
+/**
+ * The background agent a `system.notification` reports as settled, or null.
+ * `{ agentId, agentType, displayName, description, status }` — `status` is
+ * 'completed' | 'failed' for `agent_completed`, 'idle' for `agent_idle`.
+ */
+export function settledAgentFromNotification(event) {
+  if (String(event?.type || '') !== 'system.notification') return null;
+  const data = eventData(event);
+  const kind = data.kind && typeof data.kind === 'object' ? data.kind : {};
+  const type = String(kind.type || '');
+  if (!AGENT_SETTLED_NOTIFICATION_KINDS.includes(type)) return null;
+  const agentId = String(kind.agentId || '').trim();
+  if (!agentId) return null;
+  return {
+    agentId,
+    agentType: String(kind.agentType || '').trim(),
+    displayName: String(kind.displayName || '').trim(),
+    description: String(kind.description || '').trim(),
+    status: type === 'agent_idle' ? 'idle' : (String(kind.status || '').trim() || 'completed'),
+  };
+}
+
+/** A one-line transcript note for a settled background agent, posted into its continuation. */
+export function describeSettledAgent(agent) {
+  if (!agent?.agentId) return '';
+  const name = agent.displayName || agent.description || agent.agentType || 'agent';
+  const verb = agent.status === 'failed' ? 'failed' : 'finished';
+  return agent.description && agent.description !== name
+    ? `Background agent ${name} ${verb}: ${agent.description}`
+    : `Background agent ${name} ${verb}`;
+}
+
 // `<command started in detached background with shellId: 1>`
 const SHELL_OPENED_RE = /detached\s+(?:background|command)[^<>]*?shellId:\s*([^\s>,]+)/i;
 // `<detached command with shellId: 1 completed with exit code 0>`
@@ -118,7 +163,17 @@ export const CONTINUATION_OPENING_EVENT_TYPES = Object.freeze([
 
 const OPENING_TYPES = new Set(CONTINUATION_OPENING_EVENT_TYPES);
 
+/**
+ * Only ROOT-agent events open a turn. A background subagent keeps emitting
+ * `agentId`-tagged `tool.execution_start` / `assistant.message` / its own
+ * `user.message` after the turn that spawned it has settled (live-probed on
+ * runtime 1.0.88: the subagent's whole life happens under the main loop's
+ * idle), and none of that is the main agent starting work. The root agent's
+ * follow-up when the subagent finishes (`read_agent` + a reply) carries no
+ * `agentId` and opens the continuation as before.
+ */
 export function isContinuationOpeningEvent(event) {
+  if (String(event?.agentId || '').trim()) return false;
   return OPENING_TYPES.has(String(event?.type || ''));
 }
 

package/server/copilot-worker/copilot-question-bridge.mjs

@@ -23,6 +23,7 @@
 // question array. Composing the waiter instead of copying it keeps one
 // implementation of the abort semantics.
 import { createAskUserBridge } from '../../shared/ask-user-bridge.mjs';
+import { looksLikeMultiSelectQuestion } from '../../shared/question-multi-select.mjs';
 import {
   DEFAULT_QUESTION_TIMEOUT_MS,
   QUESTION_TIMEOUT_CONTINUATION_TEXT,
@@ -103,8 +104,12 @@ export function createCopilotQuestionBridge({
     await api('POST', `/api/relay-question/${questionId}/timeout`, {}).catch(() => {});
   }
 
-  async function createQuestion({ prompt, choices, allowFreeform, source, rationale, requestedSchema, timeoutMs, extra = {} }) {
-    const activeMsg = typeof getActiveMessage === 'function' ? getActiveMessage() : null;
+  async function createQuestion({ prompt, choices, allowFreeform, source, rationale, requestedSchema, timeoutMs, extra = {} }, owner) {
+    // A caller that knows which row the card belongs to names it (`message`);
+    // by the time the card is created the "active" row can be another one.
+    const activeMsg = owner !== undefined
+      ? owner
+      : (typeof getActiveMessage === 'function' ? getActiveMessage() : null);
     const payload = {
       // The relay 409s ("No active relay turn") unless this queue row is
       // `processing`, which is exactly the state a blocking handler runs in.
@@ -140,13 +145,13 @@ export function createCopilotQuestionBridge({
     return questionId;
   }
 
-  async function ask(spec, { signal } = {}) {
+  async function ask(spec, { signal, message } = {}) {
     // Shutdown already began: nothing will ever poll an answer, so minting a
     // card would only strand it in the UI. Shaped like a timeout so the caller
     // degrades exactly as it does for an unanswered card.
     if (closing) return { answer: QUESTION_TIMEOUT_CONTINUATION_TEXT, timedOut: true };
     const create = (async () => {
-      const questionId = await createQuestion(spec);
+      const questionId = await createQuestion(spec, message);
       if (closing) {
         // The create raced `cancelPendingQuestions` and lost: its card was
         // born after the shutdown snapshot, so it is expired here, at birth —
@@ -188,7 +193,7 @@ export function createCopilotQuestionBridge({
    * comes back with `structuredAnswer: null` — the caller declines in that
    * case, so a half-valid submission can never be forced into a form result.
    */
-  async function askStructured({ prompt, requestedSchema, timeoutMs }, { signal } = {}) {
+  async function askStructured({ prompt, requestedSchema, timeoutMs }, { signal, message } = {}) {
     const result = await ask({
       prompt: String(prompt || '').trim() || 'Copilot needs structured input to continue this turn.',
       choices: [],
@@ -197,7 +202,7 @@ export function createCopilotQuestionBridge({
       ...(timeoutMs === undefined ? {} : { timeoutMs }),
       source: 'onElicitationRequest',
       rationale: 'Copilot requested a structured form answer to continue this turn.',
-    }, { signal });
+    }, { signal, message });
     const structuredAnswer = result?.structuredAnswer && typeof result.structuredAnswer === 'object'
       && !Array.isArray(result.structuredAnswer)
       ? result.structuredAnswer
@@ -217,20 +222,37 @@ export function createCopilotQuestionBridge({
    * silently. A relay that is unreachable therefore degrades to the same
    * in-band note phase 1 always returned, which lets the model continue.
    */
-  async function askUserInput(request, { signal } = {}) {
+  async function askUserInput(request, { signal, message } = {}) {
     const question = String(request?.question || '').trim();
     const choices = normalizeUserInputChoices(request?.choices);
     // `allowFreeform` is only meaningful alongside choices; with none, the card
     // must accept free text or it cannot be answered.
     const allowFreeform = choices.length ? request?.allowFreeform !== false : true;
+    // Multi-select, in order of trust: the model's own flag (the relay's
+    // `ask_user` tool has `multi_select`; the runtime's built-in one has no
+    // such field), then the wording ("select all that apply"). Either way
+    // every Copilot choice card also offers the "Select several" switch
+    // (`allowMultiSelect`), because a model can forget to say so. The answer
+    // comes back as the labels joined with ", ", which the model reads as a
+    // freeform reply.
+    // A request that demands exactly one of the offered choices
+    // (`allowFreeform: false`) gets neither: a joined answer would be outside
+    // the set the runtime asked for.
+    const canPickSeveral = choices.length >= 2 && allowFreeform;
+    const multiSelect = canPickSeveral
+      && (request?.multiSelect === true || looksLikeMultiSelectQuestion(question, choices));
     const result = await ask({
       prompt: question || 'Copilot asked for input to continue this turn.',
       choices,
       allowFreeform,
-      source: 'onUserInputRequest',
+      source: String(request?.source || '').trim() || 'onUserInputRequest',
       rationale: 'Copilot requested clarification to continue this turn.',
-      extra: { requestId: String(request?.requestId || '') || undefined },
-    }, { signal });
+      extra: {
+        requestId: String(request?.requestId || '') || undefined,
+        ...(multiSelect ? { multiSelect: true } : {}),
+        ...(canPickSeveral ? { allowMultiSelect: true } : {}),
+      },
+    }, { signal, message });
     const answer = String(result?.answer ?? '');
     return {
       answer,
@@ -246,7 +268,7 @@ export function createCopilotQuestionBridge({
    * so a human can type *why* they are refusing and the model receives it as
    * feedback instead of a bare refusal.
    */
-  async function askToolApproval(request, { signal } = {}) {
+  async function askToolApproval(request, { signal, message } = {}) {
     const description = describePermissionRequest(request);
     const result = await ask({
       prompt: `Copilot wants to run:\n\n${description}\n\nApprove this action?`,
@@ -258,7 +280,7 @@ export function createCopilotQuestionBridge({
         requestId: String(request?.requestId || '') || undefined,
         permissionKind: String(request?.kind || '') || undefined,
       },
-    }, { signal });
+    }, { signal, message });
     const answer = String(result?.answer ?? '').trim();
     const approved = !result?.timedOut && answer.toLowerCase() === PERMISSION_APPROVE_CHOICE.toLowerCase();
     // The denial note is composed HERE rather than in the permission handler so

package/server/copilot-worker/copilot-remote-relay-tool.mjs

@@ -0,0 +1,59 @@
+// The relay's `remote_relay` tool for Copilot SDK sessions: a plain SDK
+// `Tool` (`{ name, description, parameters, skipPermission, handler }`) built
+// from the shared contract and forwarded through the shared tool core. The
+// module never imports the SDK; the session process hands the definition to
+// `SessionConfig.tools`.
+//
+// `skipPermission`: the relay does the approving. A write action in ask or
+// plan mode raises its own question card server-side, so a runtime permission
+// prompt on top would ask the user twice for one action.
+
+import {
+  REMOTE_RELAY_CALL_FAILED,
+  REMOTE_RELAY_TOOL_DESCRIPTION,
+  REMOTE_RELAY_TOOL_NAME,
+  cloneRemoteRelayToolInputSchema,
+  executeRemoteRelayTool,
+  formatRemoteRelayToolResult,
+} from '../../shared/remote-relay-tool-core.mjs';
+
+/**
+ * `runCall(fn)` wraps every execution — the session process uses it to hold
+ * its stall watchdog and idle shutdown while the relay waits on a remote turn.
+ * The handler never throws: a failure answers in-band as JSON the model can
+ * read, which is what the runtime passes back to it anyway.
+ *
+ * `getSignal(invocation)` is the call's cancellation. By default the SDK's
+ * own `invocation.signal`, which aborts when the runtime completes the
+ * request or the session disconnects; the session process adds the turn's
+ * Stop to it.
+ */
+export function buildCopilotRemoteRelayTool({
+  api,
+  getConversationId = () => '',
+  runCall = (fn) => fn(),
+  getSignal = (invocation) => invocation?.signal || null,
+  dbg = () => {},
+} = {}) {
+  return {
+    name: REMOTE_RELAY_TOOL_NAME,
+    description: REMOTE_RELAY_TOOL_DESCRIPTION,
+    parameters: cloneRemoteRelayToolInputSchema(),
+    skipPermission: true,
+    handler: async (args, invocation) => {
+      let result;
+      try {
+        result = await runCall(() => executeRemoteRelayTool(args, {
+          api,
+          conversationId: String(getConversationId() || ''),
+          signal: getSignal(invocation) || null,
+        }));
+      } catch (error) {
+        const message = error?.message || String(error);
+        dbg('remote_relay tool failed', message);
+        result = { ok: false, code: REMOTE_RELAY_CALL_FAILED, error: message };
+      }
+      return formatRemoteRelayToolResult(result);
+    },
+  };
+}