agent-relay-runner 0.127.5 → 0.127.7

package/src/control-server.ts

@@ -1,17 +1,16 @@
 import type { Server, ServerWebSocket } from "bun";
 import type { InteractivePrompt, Message, ReplyObligation } from "agent-relay-sdk";
 import { errMessage, isRecord } from "agent-relay-sdk";
-import type { ProviderPermissionDecisionInput, ProviderPermissionDecisionReason, ProviderStatusEvent, SemanticStatus, TerminalAttachSpec } from "./adapter";
+import type { ProviderPermissionDecisionInput, ProviderPermissionDecisionReason, ProviderPermissionPromptHandler, ProviderPermissionResolvedPrompt, ProviderStatusEvent, SemanticStatus, TerminalAttachSpec } from "./adapter";
 import { obligationRequiresExplicitReply } from "./reply-obligation-cache";
 import { relayReplyActionText } from "./relay-instructions";
 import { logger, parseLogLevel, LOG_LEVELS } from "./logger";
 import { buildRateLimitProviderState } from "./rate-limit";
 import { bestEffortDeletePendingPermissionRequest, bestEffortListPendingPermissionRequests, bestEffortUpsertPendingPermissionRequest, type PendingPermissionRequestRecord, type PendingPermissionStore } from "./pending-permission-store";
 
-// The AskUserQuestion / PermissionRequest hook (runner/plugins/claude/hooks/hooks.json)
-// has a 900s Claude-side timeout. Resolve the server-side wait with a margin UNDER that
-// so the server always returns a deterministic decision before Claude abandons the hook —
-// at exact equality the two timers race with no winner (#693).
+// Provider permission hooks can wait a long time. Resolve the server-side wait with
+// a margin under the provider hook timeout so the server returns a deterministic
+// decision before the provider abandons the hook.
 const PERMISSION_WAIT_MS = 880_000;
 // Distinct from a human dismissal ("Dismissed/Denied from Agent Relay dashboard") so the
 // agent can tell "nobody answered in time" (retriable) from "the human said no" (#693).
@@ -19,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
@@ -35,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;
@@ -47,30 +57,22 @@ interface ControlServerOptions {
   onStatus(status: ProviderStatusEvent): void;
   onTerminalAttachSpec?(): Promise<TerminalAttachSpec>;
   onReplyObligations?(): Promise<ReplyObligation[]>;
-  // Phase 1 live-session lane: a provider Stop hook hands over its transcript
-  // path so the runner can capture the assistant turn and surface it in the
-  // dashboard chat without the agent re-emitting it via /reply.
-  // isPreFlush: true signals a mid-turn call from a PreToolUse hook — flush any
-  // un-mirrored narrative before the interactive form appears in chat (#435).
-  // toolName/toolInput (#1116): the hook payload's own tool call — the exact anchor the
-  // runner settle-polls the transcript for before draining and returning. The resolved
-  // `reasoningSettled` reflects whether that anchor was actually found (vs a bounded
-  // timeout), so the interactive form can stamp an honest value instead of an assumed one.
-  // promptId (#1086): Claude's native `prompt_id` from the Stop hook payload — the
-  // stable, provider-native turn identifier used instead of a minted random UUID.
+  // Provider session-final and pre-flush hooks hand over their capture source so
+  // the runner can surface the provider turn in dashboard chat without the agent
+  // re-emitting it via /reply.
   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;
-  // A provider UserPromptSubmit hook hands over the prompt the human typed
-  // directly into the session (web terminal / TUI) so the runner can mirror it
-  // into the dashboard chat and start tailing the turn transcript for reasoning.
-  // promptId (#1086): Claude's native `prompt_id` for the turn this prompt starts.
+  // #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>;
-  // A provider session-boundary hook (Claude PreCompact / SessionEnd) signals an imminent
-  // context reset or termination so the runner can run end-of-session work (#183 pre-destroy
-  // seam: #184 context-ratio capture) before the invasive operation. `reason` is the raw
-  // provider reason (compact, clear, logout, …); transcriptPath is optional — the runner
-  // falls back to the last path it saw during the session.
+  // A provider session-boundary hook signals an imminent context reset or
+  // termination so the runner can run end-of-session work before the operation.
   onSessionBoundary?(input: { reason?: string; transcriptPath?: string }): Promise<void>;
   // Phase 1 observability (#198): a hook reporting an unhandled failure. The
   // control server already logs it FATAL; this is the seam for Phase 2 to also
@@ -81,30 +83,18 @@ interface ControlServerOptions {
   permissionWaitMs?: number;
   instanceId?: string;
   pendingPermissionStore?: PendingPermissionStore;
+  permissionPromptHandler?: ProviderPermissionPromptHandler;
+  providerSourceId?: string;
+  stopObligationPath?: string;
+  monitorUnavailableMessage?: string;
 }
 
-export interface ResolvedPermissionPrompt {
-  provider: "claude";
-  kind: "questions" | "plan" | "command" | "tool";
-  title: string;
-  body: string;
-  promptBody?: string;
-  toolName: string;
-  hookEventName: string;
-  approvalId: string;
-  decision: ProviderPermissionDecisionInput["decision"];
-  decisionLabel: string;
-  occurredAt: number;
-  resolvedAt: number;
-  decisionReason: ProviderPermissionDecisionReason;
-  questions?: unknown[];
-  answers?: Record<string, string>;
-}
+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).
@@ -134,7 +124,7 @@ export function startControlServer(options: ControlServerOptions): ControlServer
           .then((obligations) => Response.json(replyObligationSummary(obligations)))
           .catch((error) => Response.json({ error: errMessage(error) }, { status: 503 }));
       }
-      if (url.pathname === "/reply-obligations/claude-stop" && req.method === "GET") {
+      if (url.pathname === `/reply-obligations/${options.stopObligationPath ?? "turn-stop"}` && req.method === "GET") {
         if (!options.onReplyObligations) return Response.json({});
         return options.onReplyObligations()
           .then((obligations) => Response.json(replyObligationStopDecision(obligations)))
@@ -215,7 +205,7 @@ export function startControlServer(options: ControlServerOptions): ControlServer
       server.stop(true);
     },
     async deliverToMonitor(messages: Message[], timeoutMs = 30_000): Promise<number[]> {
-      if (monitors.size === 0) throw new Error("no Claude monitor connected");
+        if (monitors.size === 0) throw new Error(options.monitorUnavailableMessage ?? "no provider monitor connected");
       const deliveryId = crypto.randomUUID();
       const payload = JSON.stringify({ type: "message.deliver", deliveryId, messages });
       return await new Promise<number[]>((resolve, reject) => {
@@ -239,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: "Claude approval resolved",
-          source: "claude",
-          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;
     },
   };
@@ -316,36 +308,88 @@ function withDecisionReason(input: ProviderPermissionDecisionInput, kind: Provid
   };
 }
 
-function decisionReasonMessage(decision: ProviderPermissionDecisionInput, fallback: string): string {
-  return decision.reason || decision.decisionReason?.message || fallback;
-}
-
 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 from the transcript before the form
-  // appears in chat. The old comment here asserted the transcript already had the
-  // assistant text block at PreToolUse time — empirically false: Claude's JSONL flush is
-  // async/bursty and can lag the hook firing by a long margin. onSessionTurn now
-  // settle-polls for the exact tool_use entry that triggered this hook (toolName/
-  // toolInput below are that anchor) before draining, and honestly reports back whether
-  // it found the anchor or hit its bounded timeout — reasoningSettled reflects that,
-  // rather than an assumption nothing here confirmed.
   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 = claudePermissionApprovalView(approvalId, body, reasoningSettled);
+  const view = handler.buildView(approvalId, body, reasoningSettled);
   const waitMs = options.permissionWaitMs ?? PERMISSION_WAIT_MS;
   const hookDeadlineAt = occurredAt + waitMs;
   bestEffortUpsertPendingPermissionRequest(options.pendingPermissionStore, {
@@ -360,10 +404,10 @@ async function handlePermissionRequest(
     reason: "provider-turn",
     providerState: {
       state: "blocked",
-      reason: "permissionRequest",
+      reason: blockedReason,
       label: view.title,
-      recommendedAction: "Review the permission request in Agent Relay.",
-      source: "claude",
+      recommendedAction,
+      source: handler.source,
       pendingApproval: view,
       updatedAt: Date.now(),
     },
@@ -375,211 +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(claudeResolvedPermissionPrompt(view, decision, body, occurredAt))).catch(() => {});
+    await Promise.resolve(options.onPermissionResolved(handler.buildResolvedPrompt(view, decision, body, occurredAt))).catch(() => {});
   }
 
-  return Response.json(claudePermissionHookResponse(decision, body));
-}
-
-// Build the normalized InteractivePrompt for a Claude PreToolUse permission/question hook.
-// reasoningSettled is the caller's settle-poll result (#435/#723/#1116): true when
-// handlePermissionRequest's pre-flush confirmed the turn's reasoning was drained before
-// this view was built, false when it hit its bounded timeout without confirming. No
-// `provider` tag — the server reads the typed contract, not provider identity.
-function claudePermissionApprovalView(id: string, body: Record<string, unknown>, reasoningSettled: boolean): InteractivePrompt {
-  const toolName = typeof body.tool_name === "string" ? body.tool_name : "Tool";
-  const toolInput = isRecord(body.tool_input) ? body.tool_input : {};
-  // AskUserQuestion is not a yes/no gate — it asks the user to pick answers.
-  // Surface the structured questions so the dashboard can render a form and
-  // return the selections via an "answer" decision (handled in the hook
-  // response below as a PreToolUse allow + updatedInput).
-  if (toolName === "AskUserQuestion" && Array.isArray(toolInput.questions) && toolInput.questions.length) {
-    const count = toolInput.questions.length;
-    return {
-      id,
-      kind: "questions",
-      title: count > 1 ? `Claude is asking ${count} questions` : "Claude is asking a question",
-      body: "",
-      questions: toolInput.questions as InteractivePrompt["questions"],
-      choices: [],
-      reasoningSettled,
-    };
-  }
-  // ExitPlanMode arrives through the generic PermissionRequest hook (it doesn't
-  // match the AskUserQuestion matcher), which used to render the raw tool_input
-  // JSON with generic Approve/Deny buttons. Surface the plan as markdown with the
-  // real plan-mode choices instead. approve → allow (exit plan mode and proceed);
-  // deny → keep planning.
-  if (toolName === "ExitPlanMode") {
-    const plan = typeof toolInput.plan === "string" && toolInput.plan.trim()
-      ? toolInput.plan
-      : JSON.stringify(toolInput);
-    return {
-      id,
-      kind: "plan",
-      title: "Claude is ready to code",
-      body: plan,
-      choices: [
-        { id: "approve", label: "Approve plan" },
-        { id: "deny", label: "Keep planning" },
-      ],
-      reasoningSettled,
-    };
-  }
-  const command = typeof toolInput.command === "string" ? toolInput.command : "";
-  const description = typeof toolInput.description === "string" ? toolInput.description : "";
-  const bodyText = [
-    command || description || JSON.stringify(toolInput),
-    typeof body.cwd === "string" ? `CWD: ${body.cwd}` : "",
-    typeof body.permission_mode === "string" ? `Mode: ${body.permission_mode}` : "",
-  ].filter(Boolean).join("\n");
-  return {
-    id,
-    kind: toolName.toLowerCase() === "bash" ? "command" : "tool",
-    title: `Approve ${toolName}`,
-    body: bodyText,
-    choices: [
-      { id: "approve", label: "Approve" },
-      { id: "approve-session", label: "Approve session" },
-      { id: "deny", label: "Deny" },
-      { id: "abort", label: "Abort" },
-    ],
-    reasoningSettled,
-  };
-}
-
-function claudePermissionHookResponse(decision: ProviderPermissionDecisionInput, body: Record<string, unknown>): Record<string, unknown> {
-  // AskUserQuestion comes through a PreToolUse hook. The only way to satisfy it
-  // headlessly is permissionDecision "allow" + updatedInput carrying the answers
-  // (echoing back the original questions). A bare "allow" is not sufficient, so
-  // anything that is not a populated answer is treated as a deny.
-  if (body.hook_event_name === "PreToolUse") {
-    const toolInput = isRecord(body.tool_input) ? body.tool_input : {};
-    if (decision.decision === "answer" && decision.answers && Object.keys(decision.answers).length) {
-      return {
-        hookSpecificOutput: {
-          hookEventName: "PreToolUse",
-          permissionDecision: "allow",
-          updatedInput: { ...toolInput, answers: decision.answers },
-        },
-      };
-    }
-    return {
-	    hookSpecificOutput: {
-	        hookEventName: "PreToolUse",
-	        permissionDecision: "deny",
-	        permissionDecisionReason: decisionReasonMessage(decision, "Dismissed from Agent Relay dashboard"),
-	      },
-	    };
-  }
-  const hookEventName = "PermissionRequest";
-  // AskUserQuestion can be gated by the PermissionRequest hook instead of PreToolUse
-  // (e.g. when the PreToolUse hook returned no decision and Claude fell back to the
-  // default permission flow). The answer must still be honored, not turned into a deny
-  // (#693). PermissionRequest supports updatedInput on an allow, same as PreToolUse.
-  if (decision.decision === "answer" && decision.answers && Object.keys(decision.answers).length) {
-    const toolInput = isRecord(body.tool_input) ? body.tool_input : {};
-    return {
-      hookSpecificOutput: {
-        hookEventName,
-        decision: {
-          behavior: "allow",
-          updatedInput: { ...toolInput, answers: decision.answers },
-        },
-      },
-    };
-  }
-  if (decision.decision === "approve" || decision.decision === "approve-session") {
-    const suggestions = Array.isArray(body.permission_suggestions) ? body.permission_suggestions : [];
-    return {
-      hookSpecificOutput: {
-        hookEventName,
-        decision: {
-          behavior: "allow",
-          ...(decision.decision === "approve-session" && suggestions.length ? { updatedPermissions: suggestions } : {}),
-        },
-      },
-    };
-  }
-  return {
-    hookSpecificOutput: {
-      hookEventName,
-	    decision: {
-	        behavior: "deny",
-	        message: decisionReasonMessage(decision, "Denied from Agent Relay dashboard"),
-	        interrupt: decision.decision === "abort",
-	      },
-	    },
-  };
-}
-
-function claudeResolvedPermissionPrompt(view: InteractivePrompt, decision: ProviderPermissionDecisionInput, body: Record<string, unknown>, occurredAt: number): ResolvedPermissionPrompt {
-  const toolName = typeof body.tool_name === "string" ? body.tool_name : "Tool";
-  const toolInput = isRecord(body.tool_input) ? body.tool_input : {};
-  const kind = view.kind === "questions" || view.kind === "plan" || view.kind === "command" || view.kind === "tool"
-    ? view.kind
-    : toolName.toLowerCase() === "bash" ? "command" : "tool";
-  const questions = Array.isArray(view.questions)
-    ? view.questions
-    : Array.isArray(toolInput.questions) ? toolInput.questions : undefined;
-  const promptBody = typeof view.body === "string" ? view.body : "";
-  const decisionLabel = claudePermissionDecisionLabel(kind, decision.decision);
-  return {
-    provider: "claude",
-    kind,
-    title: typeof view.title === "string" && view.title ? view.title : `Approve ${toolName}`,
-    body: claudeResolvedPermissionBody({ kind, title: typeof view.title === "string" && view.title ? view.title : `Approve ${toolName}`, toolName, promptBody, decisionLabel, questions, answers: decision.answers }),
-    ...(promptBody ? { promptBody } : {}),
-    toolName,
-    hookEventName: typeof body.hook_event_name === "string" ? body.hook_event_name : "PermissionRequest",
-    approvalId: decision.approvalId,
-    decision: decision.decision,
-    decisionLabel,
-    decisionReason: decision.decisionReason ?? { kind: decision.decision === "deny" || decision.decision === "abort" ? "dismissed" : "answered", ...(decision.reason ? { message: decision.reason } : {}) },
-    occurredAt,
-    resolvedAt: Date.now(),
-    ...(questions ? { questions } : {}),
-    ...(decision.answers ? { answers: decision.answers } : {}),
-  };
-}
-
-function claudeResolvedPermissionBody(input: { kind: ResolvedPermissionPrompt["kind"]; title: string; toolName: string; promptBody: string; decisionLabel: string; questions?: unknown[]; answers?: Record<string, string> }): string {
-  if (input.kind === "questions") {
-    return [
-      input.title,
-      input.decisionLabel,
-      ...resolvedQuestionRows(input.questions, input.answers, input.decisionLabel).map((row) => `Q: ${row.question}\nA: ${row.answer}`),
-    ].filter(Boolean).join("\n\n");
-  }
-  const subject = input.kind === "plan" ? "Plan prompt resolved" : `${input.toolName} permission resolved`;
-  return [subject, `Decision: ${input.decisionLabel}`, input.promptBody.trim()].filter(Boolean).join("\n\n");
-}
-
-function resolvedQuestionRows(questions: unknown[] | undefined, answers: Record<string, string> | undefined, fallback: string): Array<{ question: string; answer: string }> {
-  const answerMap = answers ?? {};
-  const rows = (questions ?? []).map((question, index) => {
-    const record = question && typeof question === "object" && !Array.isArray(question) ? question as Record<string, unknown> : {};
-    const label = typeof record.question === "string" && record.question.trim()
-      ? record.question.trim()
-      : typeof record.header === "string" && record.header.trim() ? record.header.trim() : `Question ${index + 1}`;
-    const rawAnswer = answerMap[label] ?? answerMap[String(record.question ?? "")] ?? answerMap[String(record.header ?? "")];
-    return { question: label, answer: typeof rawAnswer === "string" && rawAnswer.trim() ? rawAnswer.trim() : fallback };
-  });
-  return rows.length ? rows : Object.entries(answerMap).map(([question, answer]) => ({ question, answer }));
+  return { decision, view };
 }
 
-function claudePermissionDecisionLabel(kind: ResolvedPermissionPrompt["kind"], decision: ProviderPermissionDecisionInput["decision"]): string {
-  if (kind === "questions") return decision === "answer" ? "Answered" : "Dismissed";
-  if (kind === "plan") return decision === "approve" || decision === "approve-session" ? "Approved plan" : "Kept planning";
-  if (decision === "approve-session") return "Approved for session";
-  if (decision === "approve") return "Approved";
-  if (decision === "abort") return "Aborted";
-  if (decision === "answer") return "Answered";
-  return "Denied";
+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> {
@@ -612,7 +465,7 @@ async function handleUserPrompt(req: Request, options: ControlServerOptions): Pr
   if (!prompt.trim()) return Response.json({ ok: false, reason: "prompt required" }, { status: 400 });
   const transcriptPath = isRecord(body) && typeof body.transcriptPath === "string" ? body.transcriptPath : undefined;
   const promptId = isRecord(body) && typeof body.promptId === "string" && body.promptId ? body.promptId : undefined;
-  // Fire-and-forget: the hook must not block Claude's turn on relay round-trips.
+  // Fire-and-forget: the hook must not block the provider's turn on relay round-trips.
   void Promise.resolve(options.onUserPrompt({ prompt, transcriptPath, ...(promptId ? { promptId } : {}) })).catch(() => {});
   return Response.json({ ok: true });
 }
@@ -622,7 +475,7 @@ async function handleSessionBoundary(req: Request, options: ControlServerOptions
   const body = await req.json().catch(() => null);
   const reason = isRecord(body) && typeof body.reason === "string" ? body.reason : undefined;
   const transcriptPath = isRecord(body) && typeof body.transcriptPath === "string" ? body.transcriptPath : undefined;
-  // Fire-and-forget: a PreCompact/SessionEnd hook must not block Claude compacting or exiting.
+  // Fire-and-forget: a lifecycle hook must not block the provider compacting or exiting.
   void Promise.resolve(options.onSessionBoundary({ reason, transcriptPath })).catch(() => {});
   return Response.json({ ok: true });
 }
@@ -685,8 +538,7 @@ async function handleStatus(req: Request, options: ControlServerOptions): Promis
 }
 
 // #286: the stop-failure hook reports a usage/rate-limit stall here. Build the
-// provider-neutral `blocked` state (reason rate_limit) — the same seam Claude
-// model-unavailable and Codex approvals ride — so the dashboard shows it
+// provider-neutral `blocked` state (reason rate_limit) so the dashboard shows it
 // distinctly (never as idle/available) and the relay's resume sweep can lift it
 // at reset. The agent stays `idle` underneath (the turn truly ended); the runner
 // carries the hold via its rateLimitHold field, not an active-work claim.
@@ -701,7 +553,7 @@ async function handleRateLimit(req: Request, options: ControlServerOptions): Pro
   options.onStatus({
     status: "idle",
     clear: ["subagent"],
-    providerState: buildRateLimitProviderState({ errorType, resetAt, message: errorMessage, source: "claude" }),
+    providerState: buildRateLimitProviderState({ errorType, resetAt, message: errorMessage, source: options.providerSourceId ?? "provider" }),
   });
   return Response.json({ ok: true, errorType, ...(resetAt ? { resetAt } : {}) });
 }

package/src/launch-assembly.ts

@@ -17,8 +17,8 @@ import {
   providerProvisioningHomePathFor,
 } from "./profile-home";
 import { getManifest } from "agent-relay-providers";
-import { codexHooksSupported } from "./codex-version";
-import { claudeLaunchPromptGateSettings } from "./claude-prompt-gates";
+import { codexHooksSupported } from "./adapters/codex-version";
+import { claudeLaunchPromptGateSettings } from "./adapters/claude-prompt-gates";
 import {
   materializeResolvedAssets,
   renderProvisionedHookSet,

package/src/profile-home.ts

@@ -7,7 +7,7 @@ import { getManifest } from "agent-relay-providers";
 import { profileAllowsRelayFeature, type RunnerSpawnConfig } from "./adapter";
 import { claudeRelayManual } from "./relay-instructions";
 import { providerHomeRootFromEnv } from "./config";
-import { applyClaudeConfigPromptGatePreventions } from "./claude-prompt-gates";
+import { applyClaudeConfigPromptGatePreventions } from "./adapters/claude-prompt-gates";
 
 type ProviderHome = {
   path: string;