@arnilo/prism-tools 0.0.0-stage → 0.13.0

package/coding/src/agent/ask-user-decision.ts

@@ -0,0 +1,623 @@
+/**
+ * `ask_user_decision` tool: the model proposes choices with pros/cons and the host UI asks the
+ * person through `select` (options) or `input` (a custom answer).
+ *
+ * A host without a `ui` port suspends the run through the kernel path: the package's `tool.call`
+ * hook raises `{ ask }`, the tool's `elicitation` contract carries the answer schema, and
+ * `session.resume(decisions)` delivers the answer without executing the tool. No `prism-core`
+ * dependency and no host callback.
+ *
+ * Not included in `createCodingTools` / `createAllTools` / `createReadOnlyTools`.
+ */
+import type { HostUi, JsonObject, ToolDefinition, ToolExecutionContext, ToolResult } from "@arnilo/prism";
+import { CODING_OBSERVATION_EFFECT } from "./effects.js";
+import { enforceExecutionPolicy } from "./execution-policy.js";
+import { validateCodingLimit } from "./limits.js";
+
+import type { ExecutionPolicy } from "./execution-policy.js";
+export const ASK_USER_DECISION_TOOL_NAME = "ask_user_decision" as const;
+export const ASK_USER_DECISION_SUSPEND_REASON = "ask_user_decision" as const;
+
+/** Exactly three rationale bullets per side. */
+export const ASK_USER_DECISION_RATIONALE_COUNT = 3 as const; // max pros/cons per option
+
+export const DEFAULT_MAX_ASK_USER_DECISION_OPTIONS = 6;
+export const HARD_MAX_ASK_USER_DECISION_OPTIONS = 16;
+export const DEFAULT_MAX_ASK_USER_DECISION_QUESTION_BYTES = 2_048;
+export const HARD_MAX_ASK_USER_DECISION_QUESTION_BYTES = 8_192;
+export const DEFAULT_MAX_ASK_USER_DECISION_LABEL_BYTES = 512;
+export const HARD_MAX_ASK_USER_DECISION_LABEL_BYTES = 2_048;
+export const DEFAULT_MAX_ASK_USER_DECISION_BULLET_BYTES = 512;
+export const HARD_MAX_ASK_USER_DECISION_BULLET_BYTES = 2_048;
+/** Same ceiling as question text — free-text answers stay short. */
+export const DEFAULT_MAX_ASK_USER_DECISION_CUSTOM_BYTES = DEFAULT_MAX_ASK_USER_DECISION_QUESTION_BYTES;
+export const HARD_MAX_ASK_USER_DECISION_CUSTOM_BYTES = HARD_MAX_ASK_USER_DECISION_QUESTION_BYTES;
+
+export type AskUserDecisionSelectionMode = "single" | "multiple";
+
+export interface AskUserDecisionOption {
+  readonly id: string;
+  readonly label: string;
+  /** 0..3 advantages; the host shows whatever is given. */
+  readonly pros: readonly string[];
+  /** 0..3 disadvantages; the host shows whatever is given. */
+  readonly cons: readonly string[];
+}
+
+export interface AskUserDecisionRequest {
+  readonly question: string;
+  readonly options: readonly AskUserDecisionOption[];
+  readonly selectionMode: AskUserDecisionSelectionMode;
+  readonly allowCustom: boolean;
+  readonly toolCallId: string;
+  readonly sessionId?: string;
+  readonly runId?: string;
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * Host answer shapes. Custom text is XOR with selection (v1): never both.
+ * `allowCustom` must be true for `{ customText }`.
+ */
+export type AskUserDecisionAnswer =
+  | { readonly selectedId: string; readonly selectedIds?: never; readonly customText?: never }
+  | { readonly selectedIds: readonly string[]; readonly selectedId?: never; readonly customText?: never }
+  | { readonly selectedId: string; readonly selectedIds: readonly string[]; readonly customText?: never }
+  | { readonly customText: string; readonly selectedId?: never; readonly selectedIds?: never };
+
+export type ResolvedAskUserDecisionAnswer =
+  | { readonly kind: "selection"; readonly selectedId: string; readonly selectedIds: readonly string[] }
+  | { readonly kind: "custom"; readonly customText: string };
+
+/** The sentinel option value that opens the `input` prompt when `allowCustom` is set. */
+export const ASK_USER_DECISION_CUSTOM_VALUE = "__prism_custom__" as const;
+
+export interface AskUserDecisionToolOptions {
+  /** Host UI port; without it the tool never asks and the run suspends instead. */
+  readonly ui?: HostUi;
+  readonly executionPolicy?: ExecutionPolicy;
+  readonly maxOptions?: number;
+  readonly maxQuestionBytes?: number;
+  readonly maxLabelBytes?: number;
+  readonly maxBulletBytes?: number;
+  readonly maxCustomTextBytes?: number;
+}
+
+export interface ResolvedAskUserDecisionLimits {
+  readonly maxOptions: number;
+  readonly maxQuestionBytes: number;
+  readonly maxLabelBytes: number;
+  readonly maxBulletBytes: number;
+  readonly maxCustomTextBytes: number;
+}
+
+export function resolveAskUserDecisionLimits(
+  options?: Pick<AskUserDecisionToolOptions, "maxOptions" | "maxQuestionBytes" | "maxLabelBytes" | "maxBulletBytes" | "maxCustomTextBytes">,
+): ResolvedAskUserDecisionLimits {
+  return {
+    maxOptions: validateCodingLimit(
+      "maxOptions",
+      options?.maxOptions ?? DEFAULT_MAX_ASK_USER_DECISION_OPTIONS,
+      HARD_MAX_ASK_USER_DECISION_OPTIONS,
+    ),
+    maxQuestionBytes: validateCodingLimit(
+      "maxQuestionBytes",
+      options?.maxQuestionBytes ?? DEFAULT_MAX_ASK_USER_DECISION_QUESTION_BYTES,
+      HARD_MAX_ASK_USER_DECISION_QUESTION_BYTES,
+    ),
+    maxLabelBytes: validateCodingLimit(
+      "maxLabelBytes",
+      options?.maxLabelBytes ?? DEFAULT_MAX_ASK_USER_DECISION_LABEL_BYTES,
+      HARD_MAX_ASK_USER_DECISION_LABEL_BYTES,
+    ),
+    maxBulletBytes: validateCodingLimit(
+      "maxBulletBytes",
+      options?.maxBulletBytes ?? DEFAULT_MAX_ASK_USER_DECISION_BULLET_BYTES,
+      HARD_MAX_ASK_USER_DECISION_BULLET_BYTES,
+    ),
+    maxCustomTextBytes: validateCodingLimit(
+      "maxCustomTextBytes",
+      options?.maxCustomTextBytes ?? DEFAULT_MAX_ASK_USER_DECISION_CUSTOM_BYTES,
+      HARD_MAX_ASK_USER_DECISION_CUSTOM_BYTES,
+    ),
+  };
+}
+
+function errorResult(toolCallId: string, message: string): ToolResult {
+  return {
+    toolCallId,
+    name: ASK_USER_DECISION_TOOL_NAME,
+    content: [{ type: "text", text: message }],
+    error: { message },
+  };
+}
+
+function assertByteLimit(label: string, text: string, maxBytes: number): void {
+  const bytes = Buffer.byteLength(text, "utf8");
+  if (bytes < 1 || bytes > maxBytes) {
+    throw new Error(`${label} must be 1..${maxBytes} UTF-8 bytes`);
+  }
+  if (/[\u0000-\u0008\u000B\u000C\u000E-\u001F]/.test(text)) {
+    throw new Error(`${label} contains control characters`);
+  }
+}
+
+function parseBullets(value: unknown, label: string, maxBytes: number): string[] {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value) || value.length > ASK_USER_DECISION_RATIONALE_COUNT) {
+    throw new Error(`${label} must be 0..${ASK_USER_DECISION_RATIONALE_COUNT} strings`);
+  }
+  const out: string[] = [];
+  for (let i = 0; i < value.length; i++) {
+    const item = value[i];
+    if (typeof item !== "string") {
+      throw new Error(`${label}[${i}] must be a string`);
+    }
+    const trimmed = item.trim();
+    assertByteLimit(`${label}[${i}]`, trimmed, maxBytes);
+    out.push(trimmed);
+  }
+  return out;
+}
+
+function parseSelectionMode(value: unknown): AskUserDecisionSelectionMode {
+  if (value === undefined || value === null) return "single";
+  if (value === "single" || value === "multiple") return value;
+  throw new Error('selectionMode must be "single" or "multiple"');
+}
+
+function hasSelectionFields(answer: AskUserDecisionAnswer | null | undefined): boolean {
+  if (!answer) return false;
+  if (typeof answer.selectedId === "string" && answer.selectedId.trim() !== "") return true;
+  return Array.isArray(answer.selectedIds) && answer.selectedIds.length > 0;
+}
+
+/** Normalize host answer against mode + allowCustom. Exported for tests. */
+export function resolveAskUserDecisionAnswer(
+  answer: AskUserDecisionAnswer | null | undefined,
+  selectionMode: AskUserDecisionSelectionMode,
+  options: readonly AskUserDecisionOption[],
+  gates: { readonly allowCustom: boolean; readonly maxCustomTextBytes: number },
+): ResolvedAskUserDecisionAnswer {
+  const customRaw = answer && typeof answer.customText === "string" ? answer.customText.trim() : "";
+  const hasCustom = customRaw.length > 0;
+  const hasSelection = hasSelectionFields(answer);
+
+  if (hasCustom && hasSelection) {
+    throw new Error("customText is mutually exclusive with selectedId/selectedIds");
+  }
+
+  if (hasCustom) {
+    if (!gates.allowCustom) throw new Error("customText rejected (allowCustom=false)");
+    assertByteLimit("customText", customRaw, gates.maxCustomTextBytes);
+    return { kind: "custom", customText: customRaw };
+  }
+
+  const byId = new Map(options.map((o) => [o.id, o]));
+  const rawIds: string[] = [];
+
+  if (answer && Array.isArray(answer.selectedIds)) {
+    for (const id of answer.selectedIds) {
+      if (typeof id !== "string") throw new Error("selectedIds entries must be strings");
+      rawIds.push(id.trim());
+    }
+  }
+  if (answer && typeof answer.selectedId === "string") {
+    const id = answer.selectedId.trim();
+    if (rawIds.length === 0) rawIds.push(id);
+    else if (!(rawIds.length === 1 && rawIds[0] === id)) {
+      throw new Error("selectedId and selectedIds disagree");
+    }
+  }
+
+  if (rawIds.length === 0) {
+    throw new Error(
+      gates.allowCustom
+        ? "ask() must return selectedId/selectedIds or customText"
+        : selectionMode === "multiple"
+          ? "ask() must return non-empty selectedIds"
+          : "ask() must return selectedId",
+    );
+  }
+
+  const seen = new Set<string>();
+  const selectedIds: string[] = [];
+  for (const id of rawIds) {
+    if (!byId.has(id)) throw new Error(`ask() returned unknown selectedId: ${id}`);
+    if (seen.has(id)) throw new Error(`duplicate selectedId: ${id}`);
+    seen.add(id);
+    selectedIds.push(id);
+  }
+
+  if (selectionMode === "single" && selectedIds.length !== 1) {
+    // Single accepts selectedIds only when length is exactly 1.
+    throw new Error("single selectionMode requires exactly one selected id");
+  }
+
+  return { kind: "selection", selectedIds, selectedId: selectedIds[0]! };
+}
+
+function parseAllowCustom(value: unknown): boolean {
+  if (value === undefined || value === null) return false;
+  if (typeof value !== "boolean") throw new Error("allowCustom must be a boolean");
+  return value;
+}
+
+/** Parse + validate model args into a bounded decision request. Exported for tests. */
+export function parseAskUserDecisionArgs(
+  args: Record<string, unknown>,
+  limits: ResolvedAskUserDecisionLimits,
+): {
+  question: string;
+  options: AskUserDecisionOption[];
+  selectionMode: AskUserDecisionSelectionMode;
+  allowCustom: boolean;
+} {
+  if (typeof args.question !== "string") {
+    throw new Error("question must be a string");
+  }
+  const question = args.question.trim();
+  assertByteLimit("question", question, limits.maxQuestionBytes);
+  const selectionMode = parseSelectionMode(args.selectionMode);
+  const allowCustom = parseAllowCustom(args.allowCustom);
+
+  if (!Array.isArray(args.options)) {
+    throw new Error("options must be an array");
+  }
+  if (args.options.length < 2) {
+    throw new Error("options must include at least 2 choices");
+  }
+  if (args.options.length > limits.maxOptions) {
+    throw new Error(`options exceeds maxOptions (${limits.maxOptions})`);
+  }
+
+  const seen = new Set<string>();
+  const options: AskUserDecisionOption[] = [];
+  for (let i = 0; i < args.options.length; i++) {
+    const raw = args.options[i];
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+      throw new Error(`options[${i}] must be an object`);
+    }
+    const row = raw as Record<string, unknown>;
+    if (typeof row.id !== "string") throw new Error(`options[${i}].id must be a string`);
+    const id = row.id.trim();
+    if (!/^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(id)) {
+      throw new Error(`options[${i}].id has invalid format`);
+    }
+    if (seen.has(id)) throw new Error(`duplicate option id: ${id}`);
+    seen.add(id);
+
+    if (typeof row.label !== "string") throw new Error(`options[${i}].label must be a string`);
+    const label = row.label.trim();
+    assertByteLimit(`options[${i}].label`, label, limits.maxLabelBytes);
+
+    options.push({
+      id,
+      label,
+      pros: parseBullets(row.pros, `options[${i}].pros`, limits.maxBulletBytes),
+      cons: parseBullets(row.cons, `options[${i}].cons`, limits.maxBulletBytes),
+    });
+  }
+  return { question, options, selectionMode, allowCustom };
+}
+
+/** How the host answered an `ask_user_decision` request, or that no UI could answer. */
+export type AskUserDecisionUiOutcome =
+  | { readonly kind: "answered"; readonly result: ToolResult }
+  | { readonly kind: "declined"; readonly result: ToolResult }
+  | { readonly kind: "unavailable" };
+
+/** Build the successful tool result for a resolved answer. */
+function buildAnswerResult(
+  toolCallId: string,
+  resolved: ResolvedAskUserDecisionAnswer,
+  parsed: { question: string; options: AskUserDecisionOption[]; selectionMode: AskUserDecisionSelectionMode; allowCustom: boolean },
+): ToolResult {
+  if (resolved.kind === "custom") {
+    return {
+      toolCallId,
+      name: ASK_USER_DECISION_TOOL_NAME,
+      content: [{ type: "text", text: `User provided custom answer: ${resolved.customText}` }],
+      metadata: {
+        customText: resolved.customText,
+        selectionMode: parsed.selectionMode,
+        allowCustom: parsed.allowCustom,
+        question: parsed.question,
+        options: parsed.options,
+      },
+    };
+  }
+  const selected = resolved.selectedIds.map((id) => parsed.options.find((o) => o.id === id));
+  const labelText = selected.map((o) => `"${o?.label}" (id=${o?.id})`).join(", ");
+  return {
+    toolCallId,
+    name: ASK_USER_DECISION_TOOL_NAME,
+    content: [
+      {
+        type: "text",
+        text:
+          parsed.selectionMode === "multiple" ? `User selected ${selected.length} option(s): ${labelText}.` : `User selected ${labelText}.`,
+      },
+    ],
+    metadata: {
+      selectedId: resolved.selectedId,
+      selectedIds: resolved.selectedIds,
+      selectedLabels: selected.map((o) => o?.label),
+      selectionMode: parsed.selectionMode,
+      allowCustom: parsed.allowCustom,
+      question: parsed.question,
+      options: parsed.options,
+    },
+  };
+}
+
+/**
+ * Ask through the host UI: `select` for the declared options (plus a custom sentinel when
+ * `allowCustom`), then `input` for a custom answer. A `dismissed` response yields a declined result;
+ * `unavailable` (or no UI) yields `kind: "unavailable"` so the caller can suspend the run instead of
+ * fabricating a choice. Exported so the `tool.call` gate and the tool share one path.
+ */
+export async function askUserDecisionViaUi(
+  ui: HostUi | undefined,
+  parsed: { question: string; options: AskUserDecisionOption[]; selectionMode: AskUserDecisionSelectionMode; allowCustom: boolean },
+  limits: ResolvedAskUserDecisionLimits,
+  toolCallId: string,
+): Promise<AskUserDecisionUiOutcome> {
+  if (ui === undefined) return { kind: "unavailable" };
+  const selectOptions = parsed.options.map((option) => ({ value: option.id, label: option.label }));
+  if (parsed.allowCustom) selectOptions.push({ value: ASK_USER_DECISION_CUSTOM_VALUE, label: "Other (type a custom answer)" });
+  const response = await ui.request({
+    kind: "select",
+    title: parsed.question,
+    options: selectOptions,
+    ...(parsed.selectionMode === "multiple" ? { multiple: true } : {}),
+    detail: parsed.options.map((option) => `${option.label} (id=${option.id})`).join("; "),
+  });
+  if (response.status === "unavailable") return { kind: "unavailable" };
+  if (response.status === "dismissed") return { kind: "declined", result: errorResult(toolCallId, "the user declined to answer") };
+  const selected = typeof response.value === "string" ? [response.value] : [...response.value];
+  let answer: AskUserDecisionAnswer;
+  if (parsed.allowCustom && selected.includes(ASK_USER_DECISION_CUSTOM_VALUE)) {
+    const typed = await ui.request({ kind: "input", title: parsed.question, detail: "Type your answer." });
+    if (typed.status === "unavailable") return { kind: "unavailable" };
+    if (typed.status === "dismissed") return { kind: "declined", result: errorResult(toolCallId, "the user declined to answer") };
+    answer = { customText: typed.value };
+  } else {
+    answer = parsed.selectionMode === "multiple" ? { selectedIds: selected } : { selectedId: selected[0] ?? "" };
+  }
+  let resolved: ResolvedAskUserDecisionAnswer;
+  try {
+    resolved = resolveAskUserDecisionAnswer(answer, parsed.selectionMode, parsed.options, {
+      allowCustom: parsed.allowCustom,
+      maxCustomTextBytes: limits.maxCustomTextBytes,
+    });
+  } catch (error) {
+    return { kind: "declined", result: errorResult(toolCallId, error instanceof Error ? error.message : String(error)) };
+  }
+  return { kind: "answered", result: buildAnswerResult(toolCallId, resolved, parsed) };
+}
+
+/**
+ * Create the `ask_user_decision` tool. It asks through the supplied `host.ui`; without a UI the
+ * package's `tool.call` hook suspends the run instead, so `execute` never fabricates an answer.
+ */
+export function createAskUserDecisionTool(options: AskUserDecisionToolOptions): ToolDefinition {
+  const limits = resolveAskUserDecisionLimits(options);
+  const ui = options?.ui;
+
+  return {
+    name: ASK_USER_DECISION_TOOL_NAME,
+    effect: CODING_OBSERVATION_EFFECT,
+    effects: [],
+    description:
+      "Ask the user to choose a direction when instructions are ambiguous and the choice matters. " +
+      "Provide 2+ options; each option may list up to 3 pros and up to 3 cons. " +
+      'Use selectionMode "multiple" when several options may apply together; default is single choice. ' +
+      "Set allowCustom=true only when a short free-text alternative to the listed options is acceptable " +
+      "(custom answer is mutually exclusive with selecting option ids). " +
+      "Do not use for trivia, confirmations that are already clear, or when a single safe default exists.",
+    exclusive: true,
+    parameters: {
+      type: "object",
+      properties: {
+        question: {
+          type: "string",
+          description: "Clear decision question for the user",
+        },
+        selectionMode: {
+          type: "string",
+          enum: ["single", "multiple"],
+          description: "single (default) or multiple selection",
+        },
+        allowCustom: {
+          type: "boolean",
+          description: "When true, host may return customText instead of selecting option ids (XOR). Default false.",
+        },
+        options: {
+          type: "array",
+          minItems: 2,
+          maxItems: limits.maxOptions,
+          items: {
+            type: "object",
+            properties: {
+              id: {
+                type: "string",
+                description: "Stable option id returned when selected (e.g. keep_sqlite)",
+              },
+              label: {
+                type: "string",
+                description: "User-facing option label",
+              },
+              pros: {
+                type: "array",
+                minItems: 0,
+                maxItems: ASK_USER_DECISION_RATIONALE_COUNT,
+                items: { type: "string" },
+                description: "Up to 3 advantages of this option (optional)",
+              },
+              cons: {
+                type: "array",
+                minItems: 0,
+                maxItems: ASK_USER_DECISION_RATIONALE_COUNT,
+                items: { type: "string" },
+                description: "Up to 3 disadvantages of this option (optional)",
+              },
+            },
+            required: ["id", "label"],
+            additionalProperties: false,
+          },
+          description: `2..${limits.maxOptions} options with pros/cons`,
+        },
+      },
+      required: ["question", "options"],
+      additionalProperties: false,
+    } as JsonObject,
+    // Shared elicitation mapping (Phase 8): a durable gated run surfaces this call as a
+    // kind:"elicitation" pending decision; the answer payload resolves it without executing ask().
+    // The full UX payload (question + options with pros/cons) rides on the schema's extension key.
+    elicitation: (args) => {
+      let parsed: {
+        question: string;
+        options: AskUserDecisionOption[];
+        selectionMode: AskUserDecisionSelectionMode;
+        allowCustom: boolean;
+      };
+      try {
+        parsed = parseAskUserDecisionArgs(args as Record<string, unknown>, limits);
+      } catch {
+        return undefined; // malformed args fall back to plain tool approval; execute reports the parse error
+      }
+      return {
+        schema: {
+          ...askUserDecisionResumeSchema(parsed),
+          "x-prism-ask-user-decision": toAskUserDecisionSuspendData(parsed),
+        } as unknown as JsonObject,
+        reason: parsed.question,
+        validate: (payload) => {
+          resolveAskUserDecisionAnswer(payload as unknown as AskUserDecisionAnswer, parsed.selectionMode, parsed.options, {
+            allowCustom: parsed.allowCustom,
+            maxCustomTextBytes: limits.maxCustomTextBytes,
+          });
+        },
+      };
+    },
+    async execute(args, context: ToolExecutionContext): Promise<ToolResult> {
+      const toolCallId = context.toolCallId;
+      if (context.signal?.aborted) return errorResult(toolCallId, "Operation aborted");
+
+      let parsed: {
+        question: string;
+        options: AskUserDecisionOption[];
+        selectionMode: AskUserDecisionSelectionMode;
+        allowCustom: boolean;
+      };
+      try {
+        parsed = parseAskUserDecisionArgs(args as Record<string, unknown>, limits);
+      } catch (error) {
+        return errorResult(toolCallId, error instanceof Error ? error.message : String(error));
+      }
+
+      const policyCheck = await enforceExecutionPolicy(
+        options.executionPolicy,
+        {
+          kind: "ask_user_decision",
+          operation: "ask",
+          risk: "medium",
+          metadata: {
+            optionCount: parsed.options.length,
+            optionIds: parsed.options.map((o) => o.id),
+            selectionMode: parsed.selectionMode,
+            allowCustom: parsed.allowCustom,
+            sessionId: context.sessionId,
+            runId: context.runId,
+            signal: context.signal,
+          },
+        },
+        toolCallId,
+        ASK_USER_DECISION_TOOL_NAME,
+      );
+      if (!policyCheck.allowed) return policyCheck.result;
+
+      const outcome = await askUserDecisionViaUi(ui, parsed, limits, toolCallId);
+      if (outcome.kind === "unavailable") {
+        return errorResult(toolCallId, "the host is not available to answer; the run must suspend for an answer");
+      }
+      return outcome.result;
+    },
+  };
+}
+
+/** Durable decision payload for workflow suspension `data` (no AbortSignal / secrets). */
+export interface AskUserDecisionSuspendData {
+  readonly question: string;
+  readonly options: readonly AskUserDecisionOption[];
+  readonly selectionMode: AskUserDecisionSelectionMode;
+  readonly allowCustom: boolean;
+  readonly toolCallId?: string;
+  readonly sessionId?: string;
+  readonly runId?: string;
+}
+
+/** JSON Schema describing resume `input` (= AskUserDecisionAnswer). */
+export function askUserDecisionResumeSchema(
+  request: Pick<AskUserDecisionSuspendData, "selectionMode" | "allowCustom" | "options">,
+): JsonObject {
+  const optionIds = request.options.map((o) => o.id);
+  const selectionProps: JsonObject = {
+    selectedId: { type: "string", enum: optionIds },
+    selectedIds: {
+      type: "array",
+      minItems: 1,
+      maxItems: optionIds.length,
+      items: { type: "string", enum: optionIds },
+    },
+  };
+  if (!request.allowCustom) {
+    return {
+      type: "object",
+      additionalProperties: false,
+      properties: selectionProps,
+      // Host may send either field; tool/validator enforces mode + XOR with custom.
+      anyOf: [{ required: ["selectedId"] }, { required: ["selectedIds"] }],
+    };
+  }
+  return {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      ...selectionProps,
+      customText: {
+        type: "string",
+        minLength: 1,
+        maxLength: DEFAULT_MAX_ASK_USER_DECISION_CUSTOM_BYTES,
+      },
+    },
+    anyOf: [{ required: ["selectedId"] }, { required: ["selectedIds"] }, { required: ["customText"] }],
+  };
+}
+
+/**
+ * Normalize a suspend request into durable `AskUserDecisionSuspendData`.
+ * `allowCustom` follows the tool-path default: omitted/null becomes `false`
+ * (persisted data always carries a boolean); non-boolean values fail closed
+ * at accept time with an actionable message — never at resume time.
+ */
+export function toAskUserDecisionSuspendData(request: {
+  readonly question: string;
+  readonly options: readonly AskUserDecisionOption[];
+  readonly selectionMode: AskUserDecisionSelectionMode;
+  readonly allowCustom?: boolean;
+  readonly toolCallId?: string;
+  readonly sessionId?: string;
+  readonly runId?: string;
+}): AskUserDecisionSuspendData {
+  return {
+    question: request.question,
+    options: request.options,
+    selectionMode: request.selectionMode,
+    allowCustom: parseAllowCustom(request.allowCustom),
+    ...(request.toolCallId ? { toolCallId: request.toolCallId } : {}),
+    ...(request.sessionId ? { sessionId: request.sessionId } : {}),
+    ...(request.runId ? { runId: request.runId } : {}),
+  };
+}

package/coding/src/agent/atomic-write.ts

@@ -0,0 +1,23 @@
+/**
+ * Same-directory temp + rename for crash-safe UTF-8 file replacement.
+ * Custom WriteOperations/EditOperations should provide equivalent durability.
+ */
+import { randomBytes } from "node:crypto";
+import { rename as fsRename, unlink as fsUnlink, writeFile as fsWriteFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+export async function atomicWriteUtf8File(targetPath: string, content: string, options?: { signal?: AbortSignal }): Promise<void> {
+  const dir = dirname(targetPath);
+  const tempPath = join(dir, `.prism-write-${randomBytes(8).toString("hex")}`);
+  try {
+    await fsWriteFile(tempPath, content, { encoding: "utf-8", signal: options?.signal });
+    if (options?.signal?.aborted) {
+      await fsUnlink(tempPath).catch(() => {});
+      throw new Error("Operation aborted");
+    }
+    await fsRename(tempPath, targetPath);
+  } catch (error) {
+    await fsUnlink(tempPath).catch(() => {});
+    throw error;
+  }
+}

package/coding/src/agent/bounded-file.ts

@@ -0,0 +1,21 @@
+import { open } from "node:fs/promises";
+
+/** Read one regular-file snapshot no larger than `maxBytes`; always closes its handle. */
+export async function readFileBounded(path: string, maxBytes: number, signal?: AbortSignal): Promise<Buffer> {
+  const handle = await open(path, "r");
+  try {
+    const size = (await handle.stat()).size;
+    if (size > maxBytes) throw new Error(`File exceeds ${maxBytes} byte limit`);
+    const buffer = Buffer.allocUnsafe(size);
+    let offset = 0;
+    while (offset < size) {
+      if (signal?.aborted) throw new Error("Operation aborted");
+      const { bytesRead } = await handle.read(buffer, offset, size - offset, offset);
+      if (bytesRead === 0) break;
+      offset += bytesRead;
+    }
+    return buffer.subarray(0, offset);
+  } finally {
+    await handle.close();
+  }
+}