@humwick/runner 0.0.0-stage → 0.130.1

package/src/adapters/claude-monitor-delivery-plan.ts

@@ -0,0 +1,317 @@
+import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
+import { join as joinPath } from "node:path";
+import { fitsMonitorDelivery, monitorDeliveryLineMaxChars, monitorDeliveryMaxChars } from "../adapter";
+
+export interface MonitorDeliverySection {
+  /** Persisted message id when this section represents a message; absent for delivery scaffolding. */
+  id?: number;
+  full: string;
+  stub?: string;
+  // #2310 — how to represent `full` when it (or the section it's batched with) doesn't fit under
+  // the Monitor's caps and there's no `stub` to fall back to. Only meaningful when `stub` is
+  // absent (fetchable sections always resolve via their stub).
+  //   "must-keep"  (default) — content with no get-message path and no acceptable loss (memory
+  //                 context, self-resume continuation). Spilled byte-exact to `spillDir` and
+  //                 replaced with a pointer event. Never raw-emitted, never dropped, and NEVER
+  //                 degrades to a bare disposable-style truncation: when it genuinely can't be
+  //                 delivered this cycle (no spill dir, write failure, or no reference fits the
+  //                 caps), it gets an explicit, distinct "could not be delivered" notice instead.
+  //   "disposable" — content with no get-message path but acceptable loss (delivery scaffolding
+  //                 like the reply reminder). Self-truncated with an explicit notice.
+  kind?: "must-keep" | "disposable";
+  /** Label used in a must-keep section's spill pointer / filename. Default "content". */
+  label?: string;
+}
+
+export interface MonitorDeliveryPlan {
+  events: Array<{ text: string; messageIds: number[] }>;
+}
+
+export interface PlanClaudeMonitorDeliveryOptions {
+  reservedChars?: number;
+  // #2310 — directory to spill an over-cap must-keep section's full content to (byte-exact),
+  // replacing the delivered event with a small "read this file" pointer. There is no supported
+  // way to emit more than one Monitor event per delivery cycle (the harness coalesces same-tick
+  // stdout into one event), so a must-keep section that's too large to inline can never be
+  // chunked across events — spilling to disk is the only loss-free route. Typically the agent's
+  // session scratch tmp dir (AGENT_RELAY_SCRATCH_DIR). When omitted, or the write fails, the
+  // section gets an explicit "could not be delivered" notice — NEVER raw-emitted for the harness
+  // to truncate mid-content, and never a bare/ambiguous truncation either.
+  spillDir?: string;
+}
+
+type RenderedSection = MonitorDeliverySection & { text: string };
+
+const join = (items: string[]) => items.join("\n\n");
+const idsOf = (items: Array<{ id?: number }>) => items.flatMap((item) => (item.id === undefined ? [] : [item.id]));
+const DISPOSABLE_TRUNCATION_NOTICE = "\n[…truncated]";
+
+// Cuts `text` to at most `budget` chars, further cutting a run of non-newline characters once it
+// would exceed `lineMaxChars` — the two caps the harness enforces independently. A pure prefix
+// slice (never rearranges/rewraps), so the result is always a byte-exact prefix of `text` — except
+// that the cut point is nudged back by one UTF-16 code unit when it would otherwise land inside a
+// surrogate pair (e.g. an emoji), never emitting a lone unpaired surrogate.
+function truncateToCaps(text: string, budget: number, lineMaxChars: number): string {
+  let charCount = 0;
+  let lineCount = 0;
+  let cut = 0;
+  while (cut < text.length) {
+    const ch = text[cut];
+    const nextCharCount = charCount + 1;
+    const nextLineCount = ch === "\n" ? 0 : lineCount + 1;
+    if (nextCharCount > budget || nextLineCount > lineMaxChars) break;
+    charCount = nextCharCount;
+    lineCount = nextLineCount;
+    cut++;
+  }
+  if (cut > 0 && cut < text.length) {
+    const before = text.charCodeAt(cut - 1);
+    const after = text.charCodeAt(cut);
+    if (before >= 0xd800 && before <= 0xdbff && after >= 0xdc00 && after <= 0xdfff) cut--;
+  }
+  return text.slice(0, cut);
+}
+
+function selfTruncateDisposableSection(section: RenderedSection, reserved: number): string {
+  const maxChars = monitorDeliveryMaxChars();
+  const lineMaxChars = monitorDeliveryLineMaxChars();
+  const budget = Math.max(1, maxChars - reserved - DISPOSABLE_TRUNCATION_NOTICE.length);
+  const body = truncateToCaps(section.text, budget, lineMaxChars);
+  return body.length < section.text.length ? `${body}${DISPOSABLE_TRUNCATION_NOTICE}` : body;
+}
+
+// #2310 review round 4 P0-1 — bounds on the two places a caller-supplied `label` gets embedded so
+// neither can blow a cap on its own: the filename component (unbounded here previously caused
+// ENAMETOOLONG on write, silently turning a usable spill into an undeliverable notice) and the
+// short display form used in notice/pointer text. The full uuid in the filename is NOT shortened —
+// it's already fixed-length and collision-safe; only the caller-controlled label is bounded.
+const MAX_FILENAME_LABEL_CHARS = 20;
+const MAX_DISPLAY_LABEL_CHARS = 40;
+
+function boundLabel(label: string, maxChars: number): string {
+  const trimmed = (label ?? "").trim();
+  if (!trimmed) return "content";
+  return trimmed.length > maxChars ? `${trimmed.slice(0, Math.max(1, maxChars - 1))}…` : trimmed;
+}
+
+function sanitizeForFilename(label: string): string {
+  const cleaned = label.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "content";
+  if (cleaned.length <= MAX_FILENAME_LABEL_CHARS) return cleaned;
+  return cleaned.slice(0, MAX_FILENAME_LABEL_CHARS).replace(/-+$/g, "") || "content";
+}
+
+// #2310 P1 — the spilled file (and the dir it lands in) can hold sensitive content (memory
+// context, self-resume continuation), so both are session-private: dir 0700, file 0600. `mode` on
+// mkdirSync/writeFileSync is still subject to umask, so re-assert both with chmodSync afterward —
+// best-effort (a chmod failure here shouldn't sacrifice the write; the caller's own try/catch
+// around this whole function is the real safety net if something is fundamentally unwritable).
+function writeSpillFileTight(dir: string, filePath: string, content: string): void {
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  try { chmodSync(dir, 0o700); } catch {}
+  writeFileSync(filePath, content, { encoding: "utf8", mode: 0o600 });
+  try { chmodSync(filePath, 0o600); } catch {}
+}
+
+// #2310 review round 3 P0 — a must-keep section must NEVER degrade to a bare disposable
+// truncation ("[…truncated]" with no way back to the rest) — that's indistinguishable from
+// ordinary lossy content. When it genuinely can't be delivered in full this cycle, say so
+// explicitly and distinctly instead. `reason` names WHY (surfaced verbatim to the agent).
+//
+// This IS a real, unrecovered content loss for the cycle — not a fail-closed retry. Fail-closed
+// (withhold the ack, let the caller redeliver) isn't available here: unlike a persisted/fetchable
+// message (real id, tracked through the poll+ack+requeue path), a must-keep injection is built
+// with id 0 (see runner-core.ts injectContext) specifically because it's a one-shot push with no
+// persisted-message retry contract, and its single-shot caller doesn't inspect the delivery result
+// to decide whether to re-offer it. Building real fail-closed retry would mean giving these
+// injections a trackable identity and teaching that caller to retry on a missing ack — a genuine
+// architecture change, out of scope here. The explicit notice is the honest floor: it can't
+// silently vanish, even though it can't self-heal either.
+// #2310 review round 4 P0-1 — built as a cascade of progressively SHORTER, but always
+// independently-complete, candidates — never by truncating a single label-prefixed string (a huge
+// label pushed the classified marker text itself past the caps, so a raw prefix-truncation of the
+// old label-first shape could slice down to a bare "[LLLL…" containing none of "could NOT be
+// delivered"/"content lost"). Each tier drops the LEAST essential part first (char count, then the
+// caller's label, then the specific reason) while the classified "undeliverable" marker survives
+// every tier down to the last.
+function mustKeepUndeliverableNotice(section: RenderedSection, reserved: number, reason: string): string {
+  const label = boundLabel(section.label ?? "content", MAX_DISPLAY_LABEL_CHARS);
+  const candidates = [
+    `[${label}: ${section.full.length} chars could NOT be delivered in full — ${reason}]`,
+    `[${label}: could NOT be delivered in full — ${reason}]`,
+    `[could NOT be delivered in full — ${reason}]`,
+    `[content lost — ${reason}]`,
+    `[content lost this delivery]`,
+  ];
+  for (const candidate of candidates) {
+    if (fitsMonitorDelivery(candidate, { reserved })) return candidate;
+  }
+  // Cap-safety net for a pathological cap override where even the shortest fixed-shape candidate
+  // above doesn't fit: hard-truncate the shortest (already label-free, reason-free) one as an
+  // absolute last resort — never a bare/ambiguous "[…truncated]".
+  const maxChars = monitorDeliveryMaxChars();
+  const lineMaxChars = monitorDeliveryLineMaxChars();
+  return truncateToCaps(candidates[candidates.length - 1]!, Math.max(1, maxChars - reserved), lineMaxChars);
+}
+
+// #2310 — write the section's full, untouched content to disk and point at it instead of ever
+// inlining a truncated/rewritten copy. The reference is built as a cascade of progressively
+// SHORTER but always independently-complete candidates, most useful first — never by truncating a
+// single label-prefixed string (review round 4 P0-1: a huge label must never cost us the file
+// reference itself, the one truly essential part):
+//   1. The absolute file path (most directly actionable).
+//   2. A short reference — filename plus "in your session scratch tmp dir" — for when the
+//      absolute path alone busts the per-line cap (a long cwd/agent-id; review round 3 P0 case a).
+//   3. Filename plus a terse "(scratch dir)" note, for an even tighter per-line cap.
+//   4. The bare filename alone — the filename is always short and bounded (MAX_FILENAME_LABEL_CHARS
+//      caps the label component; the fixed uuid/prefix/suffix are constant), so this should always
+//      fit even when 1-3 don't.
+// Each is tried both with and without the decorative `[label — spilled to disk, read it now]`
+// bracket line (least essential — dropped first) before escalating to a shorter reference.
+// An explicit "could not be delivered" notice is the last resort when there's no spill dir, the
+// write fails, or (pathologically) even the bare filename doesn't fit (review round 3 P0 case b).
+function spillMustKeepSection(
+  section: RenderedSection,
+  spillDir: string | undefined,
+  reserved: number,
+): { text: string; spilled: boolean } {
+  const label = section.label ?? "content";
+  if (!spillDir) return { text: mustKeepUndeliverableNotice(section, reserved, "scratch dir unavailable"), spilled: false };
+
+  let filePath: string;
+  let fileName: string;
+  try {
+    fileName = `monitor-injection-${sanitizeForFilename(label)}-${crypto.randomUUID()}.md`;
+    filePath = joinPath(spillDir, fileName);
+    writeSpillFileTight(spillDir, filePath, section.full);
+  } catch {
+    return { text: mustKeepUndeliverableNotice(section, reserved, "scratch dir write failed"), spilled: false };
+  }
+
+  const bracket = `[${boundLabel(label, MAX_DISPLAY_LABEL_CHARS)} — spilled to disk, read it now]`;
+  const references = [
+    `Full content (byte-exact): ${filePath}`,
+    `File: ${fileName} — in your session scratch tmp dir ($AGENT_RELAY_SCRATCH_DIR)`,
+    `File: ${fileName} (scratch dir)`,
+    `File: ${fileName}`,
+  ];
+  for (const reference of references) {
+    const withBracket = `${bracket}\n${reference}`;
+    if (fitsMonitorDelivery(withBracket, { reserved })) return { text: withBracket, spilled: true };
+    if (fitsMonitorDelivery(reference, { reserved })) return { text: reference, spilled: true };
+  }
+
+  // The content IS safely spilled — this only means no reference form fits THIS delivery's caps
+  // (an extreme cap override). Say so explicitly rather than silently dropping the only pointer.
+  return {
+    text: mustKeepUndeliverableNotice(section, reserved, "spilled successfully but no reference fits this delivery's caps"),
+    spilled: false,
+  };
+}
+
+type SpillResult = RenderedSection & { spilled: boolean };
+
+// #2310 review round 4 P0-2 — `items` is a mix of two DIFFERENT outcomes from spillMustKeepSection:
+// truly spilled pointers (file exists, safe to defer into an aggregate "N more spilled" count) and
+// undeliverable notices (no spillDir / write failed — nothing exists to point at). The two must
+// never be conflated: deferring an undeliverable notice into the "spilled" count is a FALSE claim
+// (the agent would go looking for a file that was never written). Keeps as many items as fit,
+// leaving room for trailing notice(s) naming exactly how many of EACH kind were deferred.
+function packWithDeferredNotice(items: SpillResult[], reserved: number): RenderedSection[] {
+  let kept: SpillResult[] = [];
+  const DEFERRED_NOTICE_BUDGET = 100;
+  for (const item of items) {
+    const candidate = [...kept, item];
+    if (fitsMonitorDelivery(join(candidate.map((entry) => entry.text)), { reserved: reserved + DEFERRED_NOTICE_BUDGET })) kept = candidate;
+  }
+  const deferred = items.filter((item) => !kept.includes(item));
+  if (deferred.length > 0) {
+    const deferredSpilled = deferred.filter((item) => item.spilled).length;
+    const deferredFailed = deferred.length - deferredSpilled;
+    const parts: string[] = [];
+    if (deferredSpilled > 0) parts.push(`${deferredSpilled} more spilled injection${deferredSpilled === 1 ? "" : "s"} — see session scratch dir`);
+    if (deferredFailed > 0) parts.push(`${deferredFailed} injection${deferredFailed === 1 ? "" : "s"} could NOT be delivered — content lost`);
+    const notice = `[${parts.join("; ")}]`;
+    kept = [...kept, { full: notice, text: notice, spilled: false }];
+  }
+  return kept;
+}
+
+/**
+ * Render each section once, then build ONE cap-compliant event (there is no supported way to emit
+ * more than one Monitor event per delivery cycle — the harness coalesces same-tick stdout back
+ * into a single event). No over-cap section is ever raw-emitted for the harness to truncate
+ * (#2310):
+ *
+ * - Every "must-keep" section (no stub, no acceptable loss — memory context, self-resume
+ *   continuation) is GUARANTEED a place in the event. #2310 P0 — with two or more oversized
+ *   must-keep sections in one delivery, EACH is spilled to its own file and every pointer is
+ *   included; none is ever silently replaced/dropped to make room for another (#2291-class: a
+ *   dropped must-keep section, unlike a dropped fetchable one, is unrecoverable — it has no
+ *   persisted id to retry via).
+ * - Fetchable (stubbed) and disposable sections are then greedily folded into whatever budget
+ *   remains around the guaranteed set. A fetchable section whose stub still doesn't fit is simply
+ *   skipped and left for the runner to requeue on the next poll (it stays retrievable via
+ *   get-message either way); a disposable section that can't be fit even self-truncated is the
+ *   one acceptable loss here.
+ */
+export function planClaudeMonitorDelivery(
+  sections: MonitorDeliverySection[],
+  options: PlanClaudeMonitorDeliveryOptions = {},
+): MonitorDeliveryPlan {
+  const reserved = options.reservedChars ?? 0;
+  const full = join(sections.map((section) => section.full));
+  if (fitsMonitorDelivery(full, { reserved })) {
+    return { events: [{ text: full, messageIds: idsOf(sections) }] };
+  }
+
+  const rendered: RenderedSection[] = sections.map((section) => ({ ...section, text: section.stub ?? section.full }));
+  const allStubbed = join(rendered.map((section) => section.text));
+  if (fitsMonitorDelivery(allStubbed, { reserved })) {
+    return { events: [{ text: allStubbed, messageIds: idsOf(rendered) }] };
+  }
+
+  const mustKeep = rendered.filter((section) => !section.stub && section.kind !== "disposable");
+  const optional = rendered.filter((section) => section.stub || section.kind === "disposable");
+
+  // Prefer each must-keep section's raw text (no unnecessary spill) when the FULL guaranteed set
+  // already fits together; only escalate to spilling ALL of them once that's not possible — a
+  // spilled pointer is small enough that the escalated set should then always coexist.
+  let guaranteed = mustKeep;
+  if (mustKeep.length > 0 && !fitsMonitorDelivery(join(mustKeep.map((item) => item.text)), { reserved })) {
+    const spilled: SpillResult[] = mustKeep.map((section) => {
+      const result = spillMustKeepSection(section, options.spillDir, reserved);
+      return { ...section, text: result.text, spilled: result.spilled };
+    });
+    if (fitsMonitorDelivery(join(spilled.map((item) => item.text)), { reserved })) {
+      guaranteed = spilled;
+    } else {
+      // Pathological (not expected in practice — pointers are small): even every pointer together
+      // doesn't fit. Every successfully spilled section is ALREADY safe on disk, so nothing from
+      // those is truly lost — keep as many items as fit and make the rest an EXPLICIT deferred
+      // count instead of silently vanishing, correctly classified as spilled vs. undeliverable.
+      guaranteed = packWithDeferredNotice(spilled, reserved);
+    }
+  }
+
+  let chunk: RenderedSection[] = guaranteed;
+  for (const section of optional) {
+    const candidate = [...chunk, section];
+    if (fitsMonitorDelivery(join(candidate.map((item) => item.text)), { reserved })) {
+      chunk = candidate;
+      continue;
+    }
+    if (section.stub) {
+      // Fetchable, but even its stub doesn't fit here — skip it (requeues on the next poll) and
+      // keep scanning; a later section must not be starved by this.
+      continue;
+    }
+    // Disposable: try a self-truncated notice instead of the (already too large) full text; if
+    // even that can't be fit alongside the guaranteed set, this is the one acceptable loss.
+    const substitute: RenderedSection = { ...section, text: selfTruncateDisposableSection(section, reserved) };
+    const withSubstitute = [...chunk, substitute];
+    if (fitsMonitorDelivery(join(withSubstitute.map((item) => item.text)), { reserved })) {
+      chunk = withSubstitute;
+    }
+  }
+  return { events: chunk.length ? [{ text: join(chunk.map((item) => item.text)), messageIds: idsOf(chunk) }] : [] };
+}

package/src/adapters/claude-permission.ts

@@ -0,0 +1,243 @@
+import type { InteractivePrompt, OperatorDecisionFileInput } from "@humwick/sdk";
+import { isRecord } from "@humwick/sdk";
+import type { ProviderPermissionDecisionInput, ProviderPermissionPromptHandler, ProviderPermissionResolvedPrompt } from "../adapter";
+
+function decisionReasonMessage(decision: ProviderPermissionDecisionInput, fallback: string): string {
+  return decision.reason || decision.decisionReason?.message || fallback;
+}
+
+export const claudePermissionPromptHandler: ProviderPermissionPromptHandler = {
+  source: "claude",
+  resolvedLabel: "Claude approval resolved",
+  buildView: claudePermissionApprovalView,
+  buildHookResponse: claudePermissionHookResponse,
+  buildResolvedPrompt: claudeResolvedPermissionPrompt,
+  buildAnswerInjectionPrompt: claudeAnswerInjectionPrompt,
+  buildDecisionRequest: claudeDecisionRequest,
+};
+
+const RECOMMENDED_LABEL = /\(recommended\)\s*$/i;
+const DECISION_TITLE_MAX = 200;
+
+// #2914: AskUserQuestion → operator decision, 1:1. Claude marks its pick with a "(Recommended)" label.
+function claudeDecisionRequest(body: Record<string, unknown>): OperatorDecisionFileInput | undefined {
+  const toolInput = isRecord(body.tool_input) ? body.tool_input : {};
+  if (body.tool_name !== "AskUserQuestion" || !Array.isArray(toolInput.questions)) return undefined;
+  const asked = toolInput.questions.filter(isRecord);
+  if (!asked.length) return undefined;
+  const questions = asked.map((question) => {
+    const options = (Array.isArray(question.options) ? question.options : []).filter(isRecord)
+      .filter((option) => typeof option.label === "string" && option.label.trim())
+      .map((option) => ({
+        label: String(option.label).trim(),
+        ...(typeof option.description === "string" && option.description.trim() ? { description: option.description.trim() } : {}),
+      }));
+    const recommended = options.findIndex((option) => RECOMMENDED_LABEL.test(option.label));
+    return {
+      prompt: typeof question.question === "string" ? question.question.trim() : "",
+      kind: !options.length ? "text" as const : question.multiSelect === true ? "multi" as const : "single" as const,
+      ...(options.length ? { options: options.map((option, index) => index === recommended ? { ...option, recommended: true } : option) } : {}),
+    };
+  });
+  const headers = asked.map((question) => typeof question.header === "string" ? question.header.trim() : "").filter(Boolean);
+  const title = headers.length ? headers.join(" · ") : questions[0]!.prompt;
+  return { title: title.length > DECISION_TITLE_MAX ? `${title.slice(0, DECISION_TITLE_MAX - 1)}…` : title, questions };
+}
+
+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 : {};
+  if (toolName === "AskUserQuestion" && Array.isArray(toolInput.questions) && toolInput.questions.length) {
+    const count = toolInput.questions.length;
+    return {
+      id,
+      kind: "questions",
+      toolName,
+      title: count > 1 ? `Claude is asking ${count} questions` : "Claude is asking a question",
+      body: "",
+      questions: toolInput.questions as InteractivePrompt["questions"],
+      choices: [],
+      reasoningSettled,
+    };
+  }
+  if (toolName === "ExitPlanMode") {
+    const plan = typeof toolInput.plan === "string" && toolInput.plan.trim()
+      ? toolInput.plan
+      : JSON.stringify(toolInput);
+    return {
+      id,
+      kind: "plan",
+      toolName,
+      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",
+    toolName,
+    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> {
+  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";
+  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): ProviderPermissionResolvedPrompt {
+  const toolName = typeof body.tool_name === "string" ? body.tool_name : "Tool";
+  const toolInput = isRecord(body.tool_input) ? body.tool_input : {};
+  const kind: ProviderPermissionResolvedPrompt["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 title = typeof view.title === "string" && view.title ? view.title : `Approve ${toolName}`;
+  const decisionLabel = claudePermissionDecisionLabel(kind, decision);
+  return {
+    provider: "claude",
+    kind,
+    title,
+    body: claudeResolvedPermissionBody({ kind, title, 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 } : {}),
+  };
+}
+
+// #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 [
+    "This was answered by the user via the Agent Relay dashboard — the AskUserQuestion tool call itself was intercepted and will not resolve; it will not return a result. Here is their answer:",
+    qa,
+    "Continue the task using their answer(s) above — do not call AskUserQuestion again for the same question(s), and do not wait for the original tool call to return.",
+  ].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 [
+      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: string, input: ProviderPermissionDecisionInput): string {
+  if (input.decisionReason?.kind === "timeout") return "Timed out";
+  const decision = input.decision;
+  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";
+}