agent-relay-runner 0.127.4 → 0.127.6

package/src/adapters/claude.ts

@@ -1,5 +1,4 @@
 import { chmodSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { type Message } from "agent-relay-sdk";
@@ -9,18 +8,22 @@ import { tmuxCommand, tmuxHasSession } from "agent-relay-sdk/tmux-utils";
 import { profileAllowsRelayFeature, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type ProviderStatusUpdate, type RunnerSpawnConfig, type SemanticStatus, type SpawnArgs } from "../adapter";
 import { computeLivenessSignal, type LivenessInputs } from "../liveness";
 import type { LivenessSignal } from "agent-relay-sdk";
-import { collectClaudeSessionEvents } from "./claude-transcript";
-import type { SessionEvent } from "../session-insights";
 import { prepareClaudeProfileHome, profileUsesClaudeHostProviderGlobals } from "../profile-home";
 import { assembleLaunch, materializeLaunchAssembly, sessionStatusLineSettingsArgs, stripSettingsArgs } from "../launch-assembly";
 import { claudeProviderMessageText } from "./claude-delivery";
 import { claudeProbeActivity, readManagedClaudeStatus, resolveClaudePid, type ClaudeProbeActivity } from "./claude-session-probe";
-import { evaluateClaudePromptGatePane, initialClaudePromptGatePaneState, type ClaudePromptGatePaneState } from "../claude-prompt-gates";
+import { evaluateClaudePromptGatePane, initialClaudePromptGatePaneState, type ClaudePromptGatePaneState } from "./claude-prompt-gates";
 import { claudePaneLooksReady, claudePaneIsBusy, claudeRateLimitStatus, claudeConnectionRetryStatus, claudeModelUnavailableStatus } from "./claude-status-detectors";
 import { launcherScriptPathForSession } from "../session-scratch";
+import { ClaudeSessionCapture, collectClaudeTranscriptArchiveSegment, collectClaudeTranscriptSessionEvents } from "./claude-session-capture";
+import { claudePermissionPromptHandler } from "./claude-permission";
 
 export class ClaudeAdapter implements ProviderAdapter {
   readonly provider = "claude";
+  readonly statusSourceId = "claude";
+  private readonly paneSourceId = `${this.statusSourceId}-pane`;
+  readonly stopObligationPath = "claude-stop";
+  readonly permissionPromptHandler = claudePermissionPromptHandler;
   readonly compactSupportsInstructions = true;
   // #352: initial prompt is seeded as Claude's positional launch arg (buildSpawnArgs) — reliable,
   // no send-keys/onboarding race; tells the runner to skip the redundant post-launch delivery.
@@ -31,6 +34,16 @@ export class ClaudeAdapter implements ProviderAdapter {
   private modelUnavailableReported = false;
   private connectionRetryActive = false;
   private promptGatePaneState: ClaudePromptGatePaneState = initialClaudePromptGatePaneState();
+  private readonly sessionCapture = new ClaudeSessionCapture();
+  readonly onSessionEvent = this.sessionCapture.onSessionEvent.bind(this.sessionCapture);
+  readonly onSessionEvents = this.sessionCapture.onSessionEvents.bind(this.sessionCapture);
+  readonly captureSessionTurn = this.sessionCapture.captureSessionTurn.bind(this.sessionCapture);
+  readonly handleUserPrompt = this.sessionCapture.handleUserPrompt.bind(this.sessionCapture);
+  readonly drainSessionTrace = this.sessionCapture.drainReasoningTail.bind(this.sessionCapture);
+  readonly settleSessionTraceForToolUse = this.sessionCapture.settlePollForToolUse.bind(this.sessionCapture);
+  readonly stopSessionTrace = this.sessionCapture.stopSessionTrace.bind(this.sessionCapture);
+  readonly collectSessionEvents = collectClaudeTranscriptSessionEvents;
+  readonly collectSessionArchiveSegment = collectClaudeTranscriptArchiveSegment;
 
   onStatusChange(cb: (status: ProviderStatusUpdate) => void): void {
     this.statusCb = cb;
@@ -91,28 +104,6 @@ export class ClaudeAdapter implements ProviderAdapter {
     return { method: "tmux-inject", command: "/clear" };
   }
 
-  // #183/#184: parse the full Claude transcript into the shared SessionEvent stream. The
-  // runner slices per-segment, so we return the whole transcript's events each call.
-  async collectSessionEvents(_process: ManagedProcess, ctx: { transcriptPath?: string }): Promise<SessionEvent[] | null> {
-    if (!ctx.transcriptPath) return null;
-    let jsonl: string;
-    try {
-      jsonl = await readFile(ctx.transcriptPath, "utf8");
-    } catch {
-      return null;
-    }
-    return collectClaudeSessionEvents(jsonl);
-  }
-
-  async collectSessionArchiveSegment(_process: ManagedProcess, ctx: { transcriptPath?: string }): Promise<string | null> {
-    if (!ctx.transcriptPath) return null;
-    try {
-      return await readFile(ctx.transcriptPath, "utf8");
-    } catch {
-      return null;
-    }
-  }
-
   async interrupt(process: ManagedProcess): Promise<Record<string, unknown>> {
     const session = process.meta?.tmuxSession as string | undefined;
     const socket = process.meta?.tmuxSocket as string | undefined;
@@ -434,6 +425,7 @@ export class ClaudeAdapter implements ProviderAdapter {
       const promptGate = evaluateClaudePromptGatePane(pane, this.promptGatePaneState, {
         sessionName,
         busy: claudePaneIsBusy(pane),
+        sourceId: this.paneSourceId,
       });
       this.promptGatePaneState = promptGate.state;
       if (promptGate.action) {

package/src/{codex-version.ts → adapters/codex-version.ts}

@@ -9,7 +9,7 @@
 // executes CODEX_HOME/hooks.json for these event names (Stop/PreToolUse/…), not just that the
 // version string clears the gate. The version probe is necessary but not sufficient.
 
-import { codexVersionOverrideFromEnv } from "./config";
+import { codexVersionOverrideFromEnv } from "../config";
 
 // Codex releases from this version on ship stable hooks with Claude-compatible events.
 const CODEX_HOOKS_MIN_VERSION = [0, 124, 0] as const;

package/src/adapters/{claude-quota-harvest.ts → provider-quota-harvest.ts}

@@ -8,20 +8,20 @@ const PASSIVE_QUOTA_SAMPLE_STALE_MS = 10 * 60_000;
 const PASSIVE_QUOTA_LEASE_MAX_TTL_MS = 10 * 60_000;
 const PASSIVE_QUOTA_LEASE_PADDING_MS = 60_000;
 
-interface ClaudeQuotaHarvestOptions {
+interface ProviderQuotaHarvestOptions {
   agentId: string;
   provider: string;
   http: () => Pick<RelayHttpClient, "acquireProviderQuotaPublisherLease" | "getProviderQuotaConfig" | "upsertProviderQuota">;
 }
 
-export class ClaudeQuotaHarvest {
+export class ProviderQuotaHarvest {
   private config = { ...DEFAULT_PROVIDER_QUOTA_CONFIG };
   private configRefreshAt = 0;
   private lastReportAt?: number;
   private lease?: { accountKey: string; leaseToken: string; expiresAt: number };
   private nextLeaseAttemptAt?: number;
 
-  constructor(private readonly options: ClaudeQuotaHarvestOptions) {}
+  constructor(private readonly options: ProviderQuotaHarvestOptions) {}
 
   async publish(): Promise<void> {
     if (this.options.provider !== "claude") return;

package/src/control-server.ts

@@ -1,21 +1,23 @@
 import type { Server, ServerWebSocket } from "bun";
-import type { InteractivePrompt, Message, ReplyObligation } from "agent-relay-sdk";
+import type { Message, ReplyObligation } from "agent-relay-sdk";
 import { errMessage, isRecord } from "agent-relay-sdk";
-import type { ProviderPermissionDecisionInput, 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).
 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;
 
 // 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
@@ -44,29 +46,17 @@ 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;
-  // 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.
+  onPermissionAbandoned?(input: PendingPermissionRequestRecord & { reason: string; decisionReason: ProviderPermissionDecisionReason }): 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
@@ -75,24 +65,15 @@ interface ControlServerOptions {
   // Test seam: how long the permission hook waits for a dashboard decision before
   // resolving as a timeout. Defaults to PERMISSION_WAIT_MS (margin under the 900s hook).
   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;
-  questions?: unknown[];
-  answers?: Record<string, string>;
-}
+export type ResolvedPermissionPrompt = ProviderPermissionResolvedPrompt;
 
 export function startControlServer(options: ControlServerOptions): ControlServer {
   const monitors = new Set<MonitorSocket>();
@@ -103,6 +84,7 @@ export function startControlServer(options: ControlServerOptions): ControlServer
   // is an idempotent no-op instead of a silent command failure (#693).
   const resolvedApprovals = new Set<string>();
   let server!: Server<MonitorSocketData>;
+  recoverStoredPermissionRequests(options);
 
   server = Bun.serve<MonitorSocketData>({
     hostname: "127.0.0.1",
@@ -126,7 +108,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)))
@@ -194,11 +176,20 @@ export function startControlServer(options: ControlServerOptions): ControlServer
       for (const pending of pendingDeliveries.values()) clearTimeout(pending.timer);
       pendingDeliveries.clear();
       for (const pending of pendingPermissionRequests.values()) clearTimeout(pending.timer);
+      for (const [approvalId, pending] of pendingPermissionRequests.entries()) {
+        const decision = withDecisionReason({
+          approvalId,
+          decision: "deny",
+          reason: PERMISSION_STOP_REASON,
+        }, "dismissed");
+        bestEffortDeletePendingPermissionRequest(options.pendingPermissionStore, approvalId);
+        pending.resolve(decision);
+      }
       pendingPermissionRequests.clear();
       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) => {
@@ -219,17 +210,17 @@ export function startControlServer(options: ControlServerOptions): ControlServer
       }
       clearTimeout(pending.timer);
       pendingPermissionRequests.delete(input.approvalId);
-      resolvedApprovals.add(input.approvalId);
-      if (resolvedApprovals.size > 1024) resolvedApprovals.clear();
-      pending.resolve(input);
+      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",
+          label: options.permissionPromptHandler?.resolvedLabel ?? "Provider approval resolved",
+          source: options.permissionPromptHandler?.source ?? options.providerSourceId ?? "provider",
           updatedAt: Date.now(),
         },
       });
@@ -238,6 +229,16 @@ export function startControlServer(options: ControlServerOptions): ControlServer
   };
 }
 
+export function recordResolvedApproval(resolvedApprovals: Set<string>, approvalId: string, limit = RESOLVED_APPROVAL_LIMIT): void {
+  resolvedApprovals.delete(approvalId);
+  resolvedApprovals.add(approvalId);
+  while (resolvedApprovals.size > limit) {
+    const oldest = resolvedApprovals.values().next().value;
+    if (!oldest) break;
+    resolvedApprovals.delete(oldest);
+  }
+}
+
 function replyObligationSummary(obligations: ReplyObligation[]): Record<string, unknown> {
   const obligation = obligations[0];
   if (!obligation) return { pending: false, count: 0 };
@@ -265,22 +266,43 @@ function replyObligationStopDecision(obligations: ReplyObligation[]): Record<str
   };
 }
 
+function recoverStoredPermissionRequests(options: ControlServerOptions): void {
+  const store = options.pendingPermissionStore;
+  if (!store) return;
+  for (const record of bestEffortListPendingPermissionRequests(store)) {
+    bestEffortDeletePendingPermissionRequest(store, record.approvalId);
+    const decisionReason: ProviderPermissionDecisionReason = {
+      kind: Date.now() >= record.hookDeadlineAt ? "timeout" : "dismissed",
+      message: Date.now() >= record.hookDeadlineAt ? PERMISSION_TIMEOUT_REASON : PERMISSION_STOP_REASON,
+    };
+    options.onPermissionAbandoned?.({ ...record, reason: decisionReason.message ?? PERMISSION_STOP_REASON, decisionReason });
+  }
+}
+
+function withDecisionReason(input: ProviderPermissionDecisionInput, kind: ProviderPermissionDecisionReason["kind"]): ProviderPermissionDecisionInput {
+  if (input.decisionReason) return input;
+  return {
+    ...input,
+    decisionReason: {
+      kind,
+      ...(input.reason ? { message: input.reason } : {}),
+    },
+  };
+}
+
 async function handlePermissionRequest(
   req: Request,
-  options: ControlServerOptions,
-  pendingPermissionRequests: Map<string, { resolve(input: ProviderPermissionDecisionInput): void; timer: Timer }>,
+	  options: ControlServerOptions,
+	  pendingPermissionRequests: Map<string, { resolve(input: ProviderPermissionDecisionInput): void; timer: Timer }>,
 ): 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.
+  // #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;
@@ -290,7 +312,16 @@ async function handlePermissionRequest(
     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, {
+    approvalId,
+    view,
+    hookDeadlineAt,
+    ownerInstanceId: options.instanceId ?? "",
+    occurredAt,
+  });
   options.onStatus({
     status: "busy",
     reason: "provider-turn",
@@ -299,7 +330,7 @@ async function handlePermissionRequest(
       reason: "permissionRequest",
       label: view.title,
       recommendedAction: "Review the permission request in Agent Relay.",
-      source: "claude",
+      source: handler.source,
       pendingApproval: view,
       updatedAt: Date.now(),
     },
@@ -308,212 +339,17 @@ async function handlePermissionRequest(
   const decision = await new Promise<ProviderPermissionDecisionInput>((resolve) => {
     const timer = setTimeout(() => {
       pendingPermissionRequests.delete(approvalId);
-      resolve({ approvalId, decision: "deny", reason: PERMISSION_TIMEOUT_REASON });
-    }, options.permissionWaitMs ?? PERMISSION_WAIT_MS);
+      bestEffortDeletePendingPermissionRequest(options.pendingPermissionStore, approvalId);
+      resolve(withDecisionReason({ approvalId, decision: "deny", reason: PERMISSION_TIMEOUT_REASON }, "timeout"));
+    }, waitMs);
     pendingPermissionRequests.set(approvalId, { resolve, timer });
   });
 
-  if (decision.reason !== PERMISSION_TIMEOUT_REASON && options.onPermissionResolved) {
-    await Promise.resolve(options.onPermissionResolved(claudeResolvedPermissionPrompt(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,
-    };
+  if (decision.decisionReason?.kind !== "timeout" && options.onPermissionResolved) {
+    await Promise.resolve(options.onPermissionResolved(handler.buildResolvedPrompt(view, decision, body, occurredAt))).catch(() => {});
   }
-  // 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: decision.reason || "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: decision.reason || "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,
-    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 }));
-}
 
-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";
+  return Response.json(handler.buildHookResponse(decision, body));
 }
 
 async function handleSessionTurn(req: Request, options: ControlServerOptions): Promise<Response> {
@@ -546,7 +382,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 });
 }
@@ -556,7 +392,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 });
 }
@@ -619,8 +455,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.
@@ -635,7 +470,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,