agent-relay-runner 0.127.6 → 0.127.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.127.6",
+  "version": "0.127.7",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-relay-runner",
   "description": "Thin Agent Relay runner bridge for Claude Code",
-  "version": "0.127.6",
+  "version": "0.127.7",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/src/adapter.ts

@@ -124,6 +124,11 @@ export interface ProviderPermissionPromptHandler {
   buildView(id: string, body: Record<string, unknown>, reasoningSettled: boolean): InteractivePrompt;
   buildHookResponse(decision: ProviderPermissionDecisionInput, body: Record<string, unknown>): Record<string, unknown>;
   buildResolvedPrompt(view: InteractivePrompt, decision: ProviderPermissionDecisionInput, body: Record<string, unknown>, occurredAt: number): ProviderPermissionResolvedPrompt;
+  // #1173: for prompt kinds whose PreToolUse hook is answered immediately (deny-then-hold —
+  // see control-server.ts's AskUserQuestion branch) rather than held open for the decision,
+  // this renders the eventual "answer" decision as the normal user-prompt text to inject back
+  // into the session. Absent for prompt kinds that still ride the hook response directly.
+  buildAnswerInjectionPrompt?(view: InteractivePrompt, decision: ProviderPermissionDecisionInput, body: Record<string, unknown>): string;
 }
 
 export interface ProviderConfig {

package/src/adapters/claude-permission.ts

@@ -12,6 +12,7 @@ export const claudePermissionPromptHandler: ProviderPermissionPromptHandler = {
   buildView: claudePermissionApprovalView,
   buildHookResponse: claudePermissionHookResponse,
   buildResolvedPrompt: claudeResolvedPermissionPrompt,
+  buildAnswerInjectionPrompt: claudeAnswerInjectionPrompt,
 };
 
 function claudePermissionApprovalView(id: string, body: Record<string, unknown>, reasoningSettled: boolean): InteractivePrompt {
@@ -155,6 +156,23 @@ function claudeResolvedPermissionPrompt(view: InteractivePrompt, decision: Provi
   };
 }
 
+// #1173: AskUserQuestion's PreToolUse hook is answered with `deny` immediately (see
+// control-server.ts) so Claude flushes its buffered reasoning instead of blocking on the human.
+// The user's actual answer arrives afterward as a normal injected prompt, not as a hook
+// response — this renders that prompt's text from the same view/decision shape the old
+// blocking flow used, so the model sees a clear, structured hand-off instead of silence.
+function claudeAnswerInjectionPrompt(view: InteractivePrompt, decision: ProviderPermissionDecisionInput, body: Record<string, unknown>): string {
+  const toolInput = isRecord(body.tool_input) ? body.tool_input : {};
+  const questions = Array.isArray(view.questions) ? view.questions : Array.isArray(toolInput.questions) ? toolInput.questions : undefined;
+  const rows = resolvedQuestionRows(questions, decision.answers, "(no answer given)");
+  const qa = rows.map((row) => `Q: ${row.question}\nA: ${row.answer}`).join("\n\n");
+  return [
+    "You previously called AskUserQuestion with the following question(s); it was intercepted so the user could answer directly via Agent Relay instead of through the tool call:",
+    qa,
+    "The user has now answered above. Continue the task using their answer(s) — do not call AskUserQuestion again for the same question(s).",
+  ].join("\n\n");
+}
+
 function claudeResolvedPermissionBody(input: { kind: string; title: string; toolName: string; promptBody: string; decisionLabel: string; questions?: unknown[]; answers?: Record<string, string> }): string {
   if (input.kind === "questions") {
     return [

package/src/control-server.ts

@@ -1,5 +1,5 @@
 import type { Server, ServerWebSocket } from "bun";
-import type { Message, ReplyObligation } from "agent-relay-sdk";
+import type { InteractivePrompt, Message, ReplyObligation } from "agent-relay-sdk";
 import { errMessage, isRecord } from "agent-relay-sdk";
 import type { ProviderPermissionDecisionInput, ProviderPermissionDecisionReason, ProviderPermissionPromptHandler, ProviderPermissionResolvedPrompt, ProviderStatusEvent, SemanticStatus, TerminalAttachSpec } from "./adapter";
 import { obligationRequiresExplicitReply } from "./reply-obligation-cache";
@@ -18,6 +18,11 @@ const PERMISSION_TIMEOUT_REASON =
   "No response received within ~15 minutes (timeout, not a dismissal). Re-ask if you still need a decision.";
 const PERMISSION_STOP_REASON = "The runner restarted while this permission request was pending; the original hook is no longer connected.";
 const RESOLVED_APPROVAL_LIMIT = 1024;
+// #1173: the immediate PreToolUse response for a "questions" prompt (see the deny-then-hold
+// branch in handlePermissionRequest below). Bridges the hand-off so the model doesn't read a
+// bare denial and re-ask — the real answer follows shortly as an injected user prompt.
+const PENDING_QUESTION_DENY_REASON =
+  "The user is answering this question directly via Agent Relay, not through this tool call — do not re-ask it. Their answer will follow as your next message; wait for it and continue from there.";
 
 // A hook that failed in a way it could not handle itself reports here so the
 // failure is never silent (#198 item 5). Phase 1 logs it FATAL to the per-agent
@@ -34,6 +39,12 @@ interface MonitorSocketData {
 
 type MonitorSocket = ServerWebSocket<MonitorSocketData>;
 
+interface PendingPermissionWaiter {
+  resolve(input: ProviderPermissionDecisionInput): void;
+  timer: Timer;
+  suppressResolvedStatus?: boolean;
+}
+
 export interface ControlServer {
   port: number;
   url: string;
@@ -52,6 +63,11 @@ interface ControlServerOptions {
   onSessionTurn?(input: { transcriptPath: string; lastAssistantMessage?: unknown; promptId?: string; isPreFlush?: boolean; toolName?: string; toolInput?: unknown }): Promise<{ reasoningSettled: boolean } | void>;
   onPermissionResolved?(input: ResolvedPermissionPrompt): Promise<void> | void;
   onPermissionAbandoned?(input: PendingPermissionRequestRecord & { reason: string; decisionReason: ProviderPermissionDecisionReason }): Promise<void> | void;
+  // #1173: a "questions" (AskUserQuestion) prompt's own PreToolUse hook is answered with `deny`
+  // immediately (see the branch in handlePermissionRequest) instead of held open for the human,
+  // so there is no live HTTP request left to answer once the decision resolves. This delivers
+  // that resolution instead: `text` is the prompt to inject as a normal user turn.
+  onAnswerInject?(input: { approvalId: string; text?: string }): Promise<void> | void;
   // A provider user-prompt hook hands over text typed directly into the session
   // so the runner can mirror it into dashboard chat.
   onUserPrompt?(input: { prompt: string; transcriptPath?: string; promptId?: string }): Promise<void>;
@@ -78,7 +94,7 @@ export type ResolvedPermissionPrompt = ProviderPermissionResolvedPrompt;
 export function startControlServer(options: ControlServerOptions): ControlServer {
   const monitors = new Set<MonitorSocket>();
   const pendingDeliveries = new Map<string, { resolve(ids: number[]): void; timer: Timer }>();
-  const pendingPermissionRequests = new Map<string, { resolve(input: ProviderPermissionDecisionInput): void; timer: Timer }>();
+  const pendingPermissionRequests = new Map<string, PendingPermissionWaiter>();
   // approvalIds already resolved, so a duplicate decision (e.g. bus replay after a
   // reconnect, or both the PreToolUse and PermissionRequest hooks racing one answer)
   // is an idempotent no-op instead of a silent command failure (#693).
@@ -213,17 +229,19 @@ export function startControlServer(options: ControlServerOptions): ControlServer
       bestEffortDeletePendingPermissionRequest(options.pendingPermissionStore, input.approvalId);
       recordResolvedApproval(resolvedApprovals, input.approvalId);
       pending.resolve(withDecisionReason(input, input.decision === "deny" || input.decision === "abort" ? "dismissed" : "answered"));
-      options.onStatus({
-        status: "busy",
-        reason: "provider-turn",
-        providerState: {
-          state: "active",
-          reason: "permissionResolved",
-          label: options.permissionPromptHandler?.resolvedLabel ?? "Provider approval resolved",
-          source: options.permissionPromptHandler?.source ?? options.providerSourceId ?? "provider",
-          updatedAt: Date.now(),
-        },
-      });
+      if (!pending.suppressResolvedStatus) {
+        options.onStatus({
+          status: "busy",
+          reason: "provider-turn",
+          providerState: {
+            state: "active",
+            reason: "permissionResolved",
+            label: options.permissionPromptHandler?.resolvedLabel ?? "Provider approval resolved",
+            source: options.permissionPromptHandler?.source ?? options.providerSourceId ?? "provider",
+            updatedAt: Date.now(),
+          },
+        });
+      }
       return true;
     },
   };
@@ -292,26 +310,85 @@ function withDecisionReason(input: ProviderPermissionDecisionInput, kind: Provid
 
 async function handlePermissionRequest(
   req: Request,
-	  options: ControlServerOptions,
-	  pendingPermissionRequests: Map<string, { resolve(input: ProviderPermissionDecisionInput): void; timer: Timer }>,
+  options: ControlServerOptions,
+  pendingPermissionRequests: Map<string, PendingPermissionWaiter>,
 ): Promise<Response> {
   const handler = options.permissionPromptHandler;
   if (!handler) return Response.json({ ok: false, reason: "permission prompt handler unavailable" }, { status: 501 });
   const occurredAt = Date.now();
   const body = await req.json().catch(() => null);
   if (!isRecord(body)) return Response.json({});
-  // #435/#1116: flush any un-mirrored narrative before the blocking form appears in
-  // chat. The adapter owns how to settle its capture source; the transport only
-  // forwards the hook payload as an anchor and stamps the returned truth value.
   const transcriptPath = typeof body.transcript_path === "string" ? body.transcript_path : "";
   const toolName = typeof body.tool_name === "string" ? body.tool_name : undefined;
   const toolInput = isRecord(body.tool_input) ? body.tool_input : undefined;
+  const approvalId = crypto.randomUUID();
+
+  // #1173: a PreToolUse "questions" prompt (the provider's AskUserQuestion) used to block this hook
+  // response for up to ~15 minutes waiting on the human — which meant the turn's reasoning that
+  // led to the question stayed buffered in the provider's process (never flushed to the transcript
+  // JSONL) for exactly as long as the human took to answer, so the dashboard could only ever
+  // show the question AFTER the reasoning that motivated it. Denying the tool call immediately
+  // is the ordinary, already-supported "rejected tool call" hook contract: the provider persists the
+  // buffered turn + a rejected tool_result right away, on its own, same as any other denied tool
+  // — so the settle-poll harvest below (previously doomed to time out for this one case) now
+  // finds the freshly-flushed anchor within moments. The human's eventual answer is delivered
+  // afterward as a normal injected prompt (see the `.then` below), not as this hook's response.
+  const probeView = handler.buildView(approvalId, body, true);
+  if (body.hook_event_name === "PreToolUse" && probeView.kind === "questions" && handler.buildAnswerInjectionPrompt) {
+    const response = Response.json(handler.buildHookResponse(
+      { approvalId, decision: "deny", reason: PENDING_QUESTION_DENY_REASON },
+      body,
+    ));
+    void awaitPermissionDecision({
+      options, pendingPermissionRequests, handler, approvalId, body, occurredAt, transcriptPath, toolName, toolInput,
+      blockedReason: "pendingQuestion",
+      recommendedAction: "Answer the question in Agent Relay.",
+      suppressResolvedStatus: true,
+    }).then(({ decision, view }) => {
+      const text = decision.decision === "answer" && decision.answers && Object.keys(decision.answers).length
+        ? handler.buildAnswerInjectionPrompt!(view, decision, body)
+        : pendingQuestionDismissalPrompt(decision);
+      return options.onAnswerInject?.({ approvalId, text });
+    }).catch(() => {});
+    return response;
+  }
+
+  const { decision } = await awaitPermissionDecision({
+    options, pendingPermissionRequests, handler, approvalId, body, occurredAt, transcriptPath, toolName, toolInput,
+    blockedReason: "permissionRequest",
+    recommendedAction: "Review the permission request in Agent Relay.",
+  });
+  return Response.json(handler.buildHookResponse(decision, body));
+}
+
+// Shared by both the traditional block-until-decided flow and the #1173 deny-then-hold flow:
+// pre-flushes narrative (#435/#1116), builds+persists the interactive view, publishes the
+// blocked providerState, and resolves once a decision arrives (or the wait times out). Callers
+// differ only in what happens with the resolved decision (build a hook response vs. inject an
+// answer prompt), so that part is left to them.
+async function awaitPermissionDecision(params: {
+  options: ControlServerOptions;
+  pendingPermissionRequests: Map<string, PendingPermissionWaiter>;
+  handler: ProviderPermissionPromptHandler;
+  approvalId: string;
+  body: Record<string, unknown>;
+  occurredAt: number;
+  transcriptPath: string;
+  toolName?: string;
+  toolInput?: unknown;
+  blockedReason: string;
+  recommendedAction: string;
+  suppressResolvedStatus?: boolean;
+}): Promise<{ decision: ProviderPermissionDecisionInput; view: InteractivePrompt }> {
+  const { options, pendingPermissionRequests, handler, approvalId, body, occurredAt, transcriptPath, toolName, toolInput, blockedReason, recommendedAction, suppressResolvedStatus } = params;
+  // #435/#1116: flush any un-mirrored narrative before the blocking form appears in
+  // chat. The adapter owns how to settle its capture source; the transport only
+  // forwards the hook payload as an anchor and stamps the returned truth value.
   let reasoningSettled = true;
   if (transcriptPath && options.onSessionTurn) {
     const result = await options.onSessionTurn({ transcriptPath, isPreFlush: true, toolName, toolInput }).catch(() => undefined);
     if (result && typeof result.reasoningSettled === "boolean") reasoningSettled = result.reasoningSettled;
   }
-  const approvalId = crypto.randomUUID();
   const view = handler.buildView(approvalId, body, reasoningSettled);
   const waitMs = options.permissionWaitMs ?? PERMISSION_WAIT_MS;
   const hookDeadlineAt = occurredAt + waitMs;
@@ -327,9 +404,9 @@ async function handlePermissionRequest(
     reason: "provider-turn",
     providerState: {
       state: "blocked",
-      reason: "permissionRequest",
+      reason: blockedReason,
       label: view.title,
-      recommendedAction: "Review the permission request in Agent Relay.",
+      recommendedAction,
       source: handler.source,
       pendingApproval: view,
       updatedAt: Date.now(),
@@ -342,14 +419,20 @@ async function handlePermissionRequest(
       bestEffortDeletePendingPermissionRequest(options.pendingPermissionStore, approvalId);
       resolve(withDecisionReason({ approvalId, decision: "deny", reason: PERMISSION_TIMEOUT_REASON }, "timeout"));
     }, waitMs);
-    pendingPermissionRequests.set(approvalId, { resolve, timer });
+    pendingPermissionRequests.set(approvalId, { resolve, timer, suppressResolvedStatus });
   });
 
   if (decision.decisionReason?.kind !== "timeout" && options.onPermissionResolved) {
     await Promise.resolve(options.onPermissionResolved(handler.buildResolvedPrompt(view, decision, body, occurredAt))).catch(() => {});
   }
 
-  return Response.json(handler.buildHookResponse(decision, body));
+  return { decision, view };
+}
+
+function pendingQuestionDismissalPrompt(decision: ProviderPermissionDecisionInput): string {
+  const timedOut = decision.decisionReason?.kind === "timeout";
+  const event = timedOut ? "timed out before the user answered" : "was dismissed before the user answered";
+  return `Your previous AskUserQuestion ${event}. Proceed on your best judgment, or re-ask if you still need a decision.`;
 }
 
 async function handleSessionTurn(req: Request, options: ControlServerOptions): Promise<Response> {

package/src/runner-core.ts

@@ -277,6 +277,12 @@ export class AgentRunner {
   // wakes one) so the blocked badge lifts on its own.
   private rateLimitHold?: ProviderState;
   private pendingRateLimitHold?: ProviderState;
+  // #1173: like rateLimitHold — a deny-then-hold "questions" (AskUserQuestion) prompt's own
+  // turn genuinely ends (the provider reacts to the denial and stops normally) before the human
+  // answers, so the pendingApproval can't ride the provider-turn active-work claim (it would
+  // vanish the instant that claim clears on the real idle). Persists across that idle; cleared
+  // once the answer is injected (or the prompt is dismissed/times out).
+  private pendingQuestionHold?: ProviderState;
   // Settle-poll cadence for the pre-flush anchor (#1116) — instance fields (not just the
   // module constants) so tests can shrink them without waiting out the real bound.
   private settlePollIntervalMs = SETTLE_POLL_INTERVAL_MS;
@@ -429,6 +435,7 @@ export class AgentRunner {
       onReplyObligations: () => Promise.resolve(this.obligationCache.get()),
       onSessionTurn: (input) => this.publishSessionTurn(input), onPermissionResolved: (input) => this.publishSessionEvent({ from: this.agentId, to: "user", body: input.body, occurredAt: input.occurredAt, session: { type: "prompt-resolution", origin: "provider", label: input.decisionLabel, ...(this.currentTurnId ? { turnId: this.currentTurnId } : {}), stepId: `prompt-resolution:${input.approvalId}`, promptResolution: input } }),
       onPermissionAbandoned: (input) => this.publishPermissionAbandonedNotice(input),
+      onAnswerInject: (input) => this.injectAnswerPrompt(input),
       onUserPrompt: (input) => this.handleUserPrompt(input),
       onSessionBoundary: (input) => this.handleSessionBoundary(input),
       onHookFatal: (report) => this.reportHookFatal(report),
@@ -926,6 +933,29 @@ export class AgentRunner {
     return { injected: true, messageId, attachmentCount: attachments.length };
   }
 
+  // #1173: the resolution side of the deny-then-hold AskUserQuestion flow (see control-server.ts's
+  // handlePermissionRequest). By the time this fires, the original PreToolUse hook has long since
+  // been answered with `deny` — there's no live HTTP request to respond to — so the human's answer
+  // (or dismissal) is delivered by clearing the pending-question hold and injecting a normal
+  // user prompt via the same path the dashboard chat box uses.
+  private async injectAnswerPrompt(input: { approvalId: string; text?: string }): Promise<void> {
+    const heldApprovalId = typeof this.pendingQuestionHold?.pendingApproval?.id === "string" ? this.pendingQuestionHold.pendingApproval.id : undefined;
+    if (heldApprovalId && heldApprovalId !== input.approvalId) return;
+    if (heldApprovalId === input.approvalId) {
+      this.pendingQuestionHold = undefined;
+      this.publishStatus();
+    }
+    const text = input.text ?? "The question was dismissed or timed out before the user answered. Proceed on your best judgment, or re-ask if you still need a decision.";
+    if (!this.process || !this.options.adapter.deliverInitialPrompt) {
+      this.sessionLog(`could not inject AskUserQuestion answer for ${input.approvalId}: provider process/prompt-injection unavailable`);
+      return;
+    }
+    this.recordInjectedPrompt(text.trim());
+    await this.options.adapter.deliverInitialPrompt(this.process, text).catch((error) => {
+      this.sessionLog(`failed to inject AskUserQuestion answer for ${input.approvalId}: ${errMessage(error)}`);
+    });
+  }
+
   private async promptInjectionText(body: string, messageId: number | undefined, attachments: Record<string, unknown>[]): Promise<string> {
     if (!attachments.length) return body;
     const messages = await messagesWithCachedAttachments([{
@@ -1251,10 +1281,18 @@ export class AgentRunner {
           this.rateLimitHold = update.providerState;
           if (fresh) this.publishRateLimitNotice(update.providerState);
         }
+      } else if (ps.state === "blocked" && ps.reason === "pendingQuestion") {
+        // #1173: set directly (never deferred) — unlike the rate-limit hold, this always
+        // arrives while the turn that asked is still busy, well before the real idle it must
+        // survive. Any other providerState (a fresh question, a plain approval, etc.) still
+        // supersedes it via the `else` branch below.
+        this.providerBlocked = true;
+        this.pendingQuestionHold = update.providerState;
       } else {
         this.providerBlocked = ps.state === "blocked";
         this.pendingRateLimitHold = undefined;
         this.rateLimitHold = undefined;
+        this.pendingQuestionHold = undefined;
       }
     } else if (status === "idle") {
       this.providerBlocked = false;
@@ -1313,6 +1351,12 @@ export class AgentRunner {
         this.currentTurnStartedAt = Date.now();
         this.compactionMidTurn = false;
         this.sessionLog(`turn started (turn ${this.currentTurnId})`);
+        // #1173: a genuinely new turn starting (not the mid-turn busy update that sets the
+        // hold itself — that arrives while currentTurnId is already set) means the human moved
+        // on without using the form (a fresh message, a self-resume, etc.). The normal
+        // answer/dismiss path already cleared this; this is the fallback for every other way
+        // forward progress can happen, so a stale question never lingers past its own turn.
+        this.pendingQuestionHold = undefined;
       }
       id = this.currentTurnId;
       this.busyReconciler.arm();
@@ -1904,7 +1948,7 @@ export class AgentRunner {
     const staleProviderTurnBusy = this.isStaleProviderTurnOnlyBusy(status, activeWork, busyReasons, liveness);
     const effectiveStatus = staleProviderTurnBusy ? "idle" : status;
     const agentStatus = runnerAgentStatus(effectiveStatus);
-    const providerState = terminalFailure?.providerState ?? this.rateLimitHold ?? (staleProviderTurnBusy ? null : providerStateFromActiveWork(activeWork));
+    const providerState = terminalFailure?.providerState ?? this.rateLimitHold ?? this.pendingQuestionHold ?? (staleProviderTurnBusy ? null : providerStateFromActiveWork(activeWork));
     this.bus.setSemanticStatus(effectiveStatus === "offline" || effectiveStatus === "error" ? "idle" : effectiveStatus);
     this.bus.status({
       agentStatus,