@lucascouts/claude-agent-acp-plus 0.1.0

package/dist/agent-name.d.ts

@@ -0,0 +1,3 @@
+export declare function agentNameFromPackageName(name: string): string;
+export declare const agentName: string;
+//# sourceMappingURL=agent-name.d.ts.map

package/dist/agent-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-name.d.ts","sourceRoot":"","sources":["../src/agent-name.ts"],"names":[],"mappings":"AASA,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7D;AAKD,eAAO,MAAM,SAAS,QAA6C,CAAC"}

package/dist/agent-name.js

@@ -0,0 +1,15 @@
+// Single import point for the adapter's announced agent identity (R2.1, R2.2).
+// This file must stay top-level in src/: it compiles to dist/agent-name.js,
+// where the `../package.json` relative import still resolves. A subdirectory
+// placement would compile to dist/<subdir>/ and break that path.
+import packageJson from "../package.json" with { type: "json" };
+// Strips a leading npm scope (`@scope/`) from a package name; unscoped names
+// pass through unchanged. Anchored replace (not split("/")) so an unscoped
+// name is never mangled.
+export function agentNameFromPackageName(name) {
+    return name.replace(/^@[^/]+\//, "");
+}
+// The agent name this adapter announces over ACP, derived from its own
+// package.json `name` — e.g. "@lucascouts/claude-agent-acp-fork" →
+// "claude-agent-acp-fork". Consumed by the ACP initialize wiring.
+export const agentName = agentNameFromPackageName(packageJson.name);

package/dist/ask-user-question-fallback.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Fallback for the built-in AskUserQuestion tool when the connected client does
+ * NOT advertise `elicitation.form`. Upstream disables the tool for such clients;
+ * this module lets the agent instead route each question through ACP's
+ * `session/request_permission` dialog. The path is gated by the
+ * `ACP_ASKUSERQUESTION_FALLBACK` env var so it can be turned off to restore
+ * byte-for-byte upstream behavior.
+ *
+ * Alongside the env gate this module provides the pure mapping/orchestration
+ * helpers (`questionPermissionOptions`, `handleAskUserQuestionViaPermission`);
+ * the ACP client is injected by the adapter that wires them in.
+ */
+import type { PermissionOption } from "@agentclientprotocol/sdk";
+import { type AskUserQuestion } from "./elicitation.js";
+/**
+ * Whether the AskUserQuestion permission fallback is enabled for clients lacking
+ * `elicitation.form`. Defaults ON: only an explicit `0` or `false` (trimmed,
+ * case-insensitive) turns it off; any other value — unset, `1`, `true`, … —
+ * leaves it on.
+ *
+ * @param env Environment map to read `ACP_ASKUSERQUESTION_FALLBACK` from (pass
+ *   `process.env`).
+ */
+export declare function askUserQuestionFallbackEnabled(env: Record<string, string | undefined>): boolean;
+/**
+ * Map one AskUserQuestion question to the options shown in ACP's
+ * `session/request_permission` dialog: one `allow_once` option per choice (in
+ * order) followed by a trailing `reject_once` "Skip this question" option.
+ *
+ * Each choice's `optionId` is its bare `label` — the value the tool records as
+ * the answer — so the description is never folded into the id; a non-empty
+ * `description` is instead appended to the human-readable `name` as
+ * `"<label> — <description>"`. The skip option is given a random `optionId`
+ * that cannot collide with any label, so the orchestrator can recognize a skip
+ * by id alone.
+ *
+ * @param question The single question whose choices become permission options.
+ */
+export declare function questionPermissionOptions(question: AskUserQuestion): PermissionOption[];
+/**
+ * Route an AskUserQuestion tool call through ACP permission requests rather than
+ * a form elicitation, for clients that lack `elicitation.form`. Each question is
+ * asked sequentially via the injected `requestPermission`; the selected label is
+ * accumulated into `answers` (keyed by the question text), a skipped question is
+ * omitted, and a multi-select question naturally degrades to a single label
+ * since each option is single-select here.
+ *
+ * Mirrors the upstream form handler's contract: input with no parseable
+ * questions denies with the identical message, and an aborted signal or a
+ * cancelled request throws `"Tool use aborted"`, discarding every accumulated
+ * answer. On success it returns the original `toolInput` augmented with
+ * `answers` as `updatedInput`.
+ *
+ * Pure and injectable — the real ACP client is wired in by the adapter — so the
+ * orchestration can be exercised without a transport.
+ *
+ * @param toolInput Raw AskUserQuestion tool input (expected to carry `questions`).
+ * @param requestPermission Injected permission-request function, invoked once per
+ *   question, resolving to the user's selection or a cancellation.
+ * @param signal Abort signal for the tool call; checked on entry and around each
+ *   request.
+ */
+export declare function handleAskUserQuestionViaPermission(toolInput: Record<string, unknown>, requestPermission: (req: {
+    question: AskUserQuestion;
+    options: PermissionOption[];
+}) => Promise<{
+    outcome: "selected";
+    optionId: string;
+} | {
+    outcome: "cancelled";
+}>, signal: AbortSignal): Promise<{
+    behavior: "allow";
+    updatedInput: Record<string, unknown>;
+} | {
+    behavior: "deny";
+    message: string;
+}>;
+//# sourceMappingURL=ask-user-question-fallback.d.ts.map

package/dist/ask-user-question-fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask-user-question-fallback.d.ts","sourceRoot":"","sources":["../src/ask-user-question-fallback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAA2B,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEjF;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,OAAO,CAO/F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,eAAe,GAAG,gBAAgB,EAAE,CAYvF;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,kCAAkC,CACtD,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,iBAAiB,EAAE,CAAC,GAAG,EAAE;IACvB,QAAQ,EAAE,eAAe,CAAC;IAC1B,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B,KAAK,OAAO,CAAC;IAAE,OAAO,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,WAAW,CAAA;CAAE,CAAC,EACnF,MAAM,EAAE,WAAW,GAClB,OAAO,CACN;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAC5D;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CACxC,CAyBA"}

package/dist/ask-user-question-fallback.js

@@ -0,0 +1,104 @@
+/**
+ * Fallback for the built-in AskUserQuestion tool when the connected client does
+ * NOT advertise `elicitation.form`. Upstream disables the tool for such clients;
+ * this module lets the agent instead route each question through ACP's
+ * `session/request_permission` dialog. The path is gated by the
+ * `ACP_ASKUSERQUESTION_FALLBACK` env var so it can be turned off to restore
+ * byte-for-byte upstream behavior.
+ *
+ * Alongside the env gate this module provides the pure mapping/orchestration
+ * helpers (`questionPermissionOptions`, `handleAskUserQuestionViaPermission`);
+ * the ACP client is injected by the adapter that wires them in.
+ */
+import { randomUUID } from "node:crypto";
+import { extractAskUserQuestions } from "./elicitation.js";
+/**
+ * Whether the AskUserQuestion permission fallback is enabled for clients lacking
+ * `elicitation.form`. Defaults ON: only an explicit `0` or `false` (trimmed,
+ * case-insensitive) turns it off; any other value — unset, `1`, `true`, … —
+ * leaves it on.
+ *
+ * @param env Environment map to read `ACP_ASKUSERQUESTION_FALLBACK` from (pass
+ *   `process.env`).
+ */
+export function askUserQuestionFallbackEnabled(env) {
+    const raw = env.ACP_ASKUSERQUESTION_FALLBACK;
+    if (raw === undefined) {
+        return true;
+    }
+    const normalized = raw.trim().toLowerCase();
+    return normalized !== "0" && normalized !== "false";
+}
+/**
+ * Map one AskUserQuestion question to the options shown in ACP's
+ * `session/request_permission` dialog: one `allow_once` option per choice (in
+ * order) followed by a trailing `reject_once` "Skip this question" option.
+ *
+ * Each choice's `optionId` is its bare `label` — the value the tool records as
+ * the answer — so the description is never folded into the id; a non-empty
+ * `description` is instead appended to the human-readable `name` as
+ * `"<label> — <description>"`. The skip option is given a random `optionId`
+ * that cannot collide with any label, so the orchestrator can recognize a skip
+ * by id alone.
+ *
+ * @param question The single question whose choices become permission options.
+ */
+export function questionPermissionOptions(question) {
+    const options = question.options.map((option) => ({
+        kind: "allow_once",
+        optionId: option.label,
+        name: option.description ? `${option.label} — ${option.description}` : option.label,
+    }));
+    options.push({
+        kind: "reject_once",
+        name: "Skip this question",
+        optionId: randomUUID(),
+    });
+    return options;
+}
+/**
+ * Route an AskUserQuestion tool call through ACP permission requests rather than
+ * a form elicitation, for clients that lack `elicitation.form`. Each question is
+ * asked sequentially via the injected `requestPermission`; the selected label is
+ * accumulated into `answers` (keyed by the question text), a skipped question is
+ * omitted, and a multi-select question naturally degrades to a single label
+ * since each option is single-select here.
+ *
+ * Mirrors the upstream form handler's contract: input with no parseable
+ * questions denies with the identical message, and an aborted signal or a
+ * cancelled request throws `"Tool use aborted"`, discarding every accumulated
+ * answer. On success it returns the original `toolInput` augmented with
+ * `answers` as `updatedInput`.
+ *
+ * Pure and injectable — the real ACP client is wired in by the adapter — so the
+ * orchestration can be exercised without a transport.
+ *
+ * @param toolInput Raw AskUserQuestion tool input (expected to carry `questions`).
+ * @param requestPermission Injected permission-request function, invoked once per
+ *   question, resolving to the user's selection or a cancellation.
+ * @param signal Abort signal for the tool call; checked on entry and around each
+ *   request.
+ */
+export async function handleAskUserQuestionViaPermission(toolInput, requestPermission, signal) {
+    if (signal.aborted) {
+        throw new Error("Tool use aborted");
+    }
+    const questions = extractAskUserQuestions(toolInput);
+    if (!questions) {
+        return { behavior: "deny", message: "AskUserQuestion called with no valid questions." };
+    }
+    const answers = {};
+    for (const question of questions) {
+        const options = questionPermissionOptions(question);
+        const skipOptionId = options.find((option) => option.kind === "reject_once")?.optionId;
+        const outcome = await requestPermission({ question, options });
+        if (outcome.outcome === "cancelled" || signal.aborted) {
+            throw new Error("Tool use aborted");
+        }
+        if (outcome.optionId === skipOptionId) {
+            continue;
+        }
+        answers[question.question] = outcome.optionId;
+    }
+    return { behavior: "allow", updatedInput: { ...toolInput, answers } };
+}

package/dist/elicitation.d.ts

@@ -0,0 +1,129 @@
+import type { CreateElicitationRequest, CreateElicitationResponse } from "@agentclientprotocol/sdk";
+import type { ElicitationRequest, ElicitationResult } from "@anthropic-ai/claude-agent-sdk";
+import type { AskUserQuestionInput } from "@anthropic-ai/claude-agent-sdk/sdk-tools.js";
+/**
+ * Bridges between the Claude Agent SDK's elicitation/dialog callbacks and ACP's
+ * (unstable) elicitation protocol.
+ *
+ * Two distinct SDK surfaces flow through here:
+ *
+ *   1. `onElicitation` — fired when an MCP server requests user input. These map
+ *      directly onto ACP `session/create_elicitation` (form or url mode).
+ *   2. The built-in AskUserQuestion tool — when a `canUseTool` callback is
+ *      registered the SDK routes its permission check through `canUseTool`
+ *      (not the interactive `permission_ask_user_question` dialog). We render
+ *      its questions as an ACP form elicitation and feed the user's selections
+ *      back as the tool's `updatedInput`, which the tool's own `call()` reads.
+ */
+/** Modes the connected client advertised support for. */
+export type ElicitationSupport = {
+    form: boolean;
+    url: boolean;
+};
+/**
+ * Convert an MCP elicitation request (from the SDK's `onElicitation` callback)
+ * into an ACP `CreateElicitationRequest`. Returns `null` when the request can't
+ * be represented (e.g. a url-mode request with no url).
+ */
+export declare function mcpElicitationToCreateRequest(request: ElicitationRequest, sessionId: string): CreateElicitationRequest | null;
+/**
+ * Map an ACP elicitation response back to the MCP `ElicitResult` the SDK expects
+ * to hand back to the requesting server.
+ */
+export declare function createElicitationResponseToElicitResult(response: CreateElicitationResponse): ElicitationResult;
+/**
+ * A single question as supplied by the AskUserQuestion tool. Derived from the
+ * SDK's input type so the shape stays in sync; the SDK validates the model's
+ * tool call against this schema before it reaches us.
+ */
+export type AskUserQuestion = AskUserQuestionInput["questions"][number];
+/**
+ * Pull the well-formed questions out of an AskUserQuestion tool input. Returns
+ * `null` when there are no usable questions — including the case where every
+ * entry is malformed and filtering leaves an empty list — so callers can treat
+ * "nothing to ask" uniformly.
+ */
+export declare function extractAskUserQuestions(input: Record<string, unknown>): AskUserQuestion[] | null;
+/**
+ * Render the AskUserQuestion tool's questions as an ACP form elicitation.
+ *
+ * Fields are keyed by a short stable id (`question_<n>`) rather than the full
+ * question text, so the question text appears in exactly one place per field.
+ * Single-select questions use a titled `oneOf` enum; multi-select questions use
+ * an array with a titled `anyOf` item enum. The enum `const` is always the
+ * option label, since that is what the tool records as the answer; an option's
+ * secondary text travels in the enum option's own `description` field.
+ *
+ * Each question is followed by its own optional free-text "custom answer" field
+ * (`question_<n>_custom`), mirroring the CLI's per-question "Other" box: the
+ * user can type their own answer instead of picking an option, scoped to that
+ * specific question. Nothing is marked required, so the user can also just skip
+ * — matching the built-in tool, which always offers Skip + a free-text box.
+ */
+export declare function askUserQuestionsToCreateRequest(questions: AskUserQuestion[], sessionId: string, toolCallId: string | undefined): CreateElicitationRequest;
+/** Outcome of an AskUserQuestion elicitation, decoupled from any transport. */
+export type AskUserQuestionOutcome = {
+    action: "answered";
+    updatedInput: Record<string, unknown>;
+} | {
+    action: "cancel";
+};
+/**
+ * Fold an ACP elicitation response into the AskUserQuestion tool's input.
+ *
+ * Selected labels are read back from the indexed form fields and written into
+ * `answers` as a `{ [questionText]: label }` map (comma-joining multi-selects)
+ * — the key shape the tool's own `call()` reads. A non-empty per-question
+ * custom-answer field (`question_<n>_custom`) takes precedence over that
+ * question's selection, since the user typed their own answer instead of
+ * picking one. Decline yields empty answers (the model is told the user skipped
+ * rather than the turn aborting); cancel — and any custom/future action we
+ * don't understand — aborts the tool call.
+ */
+export declare function applyAskElicitationResponse(response: CreateElicitationResponse, toolInput: Record<string, unknown>, questions: AskUserQuestion[]): AskUserQuestionOutcome;
+/**
+ * The `request_user_dialog` kind the CLI emits when a model refusal has a
+ * fallback available but needs user consent before retrying (e.g. Claude Fable
+ * declining a request with Opus available as the fallback). Declaring this
+ * kind in `supportedDialogKinds` is the opt-in: the CLI fails closed and never
+ * emits an undeclared kind — the flow degrades to the classic refusal error
+ * ending the turn.
+ */
+export declare const REFUSAL_FALLBACK_DIALOG_KIND = "refusal_fallback_prompt";
+/**
+ * Payload of the `refusal_fallback_prompt` dialog. The dialog protocol
+ * transports payloads opaquely, so this shape is recovered from the CLI's own
+ * schema (v2.1.177): `originalModel`/`fallbackModel` are required strings;
+ * `apiRefusalCategory` (nullable), `guidanceText`, and
+ * `retractedMessageUuids` are optional. We ignore `retractedMessageUuids` —
+ * ACP has no way to retract already-streamed chunks.
+ */
+export type RefusalFallbackPrompt = {
+    originalModel: string;
+    fallbackModel: string;
+    apiRefusalCategory: string | null;
+    guidanceText?: string;
+};
+/**
+ * Validate the opaque dialog payload into a {@link RefusalFallbackPrompt}.
+ * Returns `null` when the required fields are missing or mistyped (a newer CLI
+ * may reshape the payload), so the caller can cancel the dialog and let the
+ * CLI apply its default behavior instead of rendering something misleading.
+ */
+export declare function extractRefusalFallbackPrompt(payload: Record<string, unknown>): RefusalFallbackPrompt | null;
+/**
+ * Render the refusal-fallback consent prompt as an ACP form elicitation: a
+ * single-select between retrying on the fallback model and keeping the
+ * refusal. The enum `const`s are the dialog's wire result values, so the
+ * response maps back without a translation table.
+ */
+export declare function refusalFallbackToCreateRequest(prompt: RefusalFallbackPrompt, sessionId: string): CreateElicitationRequest;
+/**
+ * Map the elicitation response back to the dialog's result enum. Only an
+ * explicit accept-with-retry resolves to `retry_fallback`; decline, cancel, a
+ * skipped field, or an unrecognized value all keep the refusal — the dialog's
+ * own default — so a dismissed or half-filled form can never trigger a model
+ * switch the user didn't ask for.
+ */
+export declare function refusalFallbackResultFromResponse(response: CreateElicitationResponse): string;
+//# sourceMappingURL=elicitation.d.ts.map

package/dist/elicitation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elicitation.d.ts","sourceRoot":"","sources":["../src/elicitation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,wBAAwB,EACxB,yBAAyB,EAM1B,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAC5F,OAAO,KAAK,EACV,oBAAoB,EAErB,MAAM,6CAA6C,CAAC;AAErD;;;;;;;;;;;;;GAaG;AAEH,yDAAyD;AACzD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,EAAE,OAAO,CAAC;CACd,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,kBAAkB,EAC3B,SAAS,EAAE,MAAM,GAChB,wBAAwB,GAAG,IAAI,CAyBjC;AAyCD;;;GAGG;AACH,wBAAgB,uCAAuC,CACrD,QAAQ,EAAE,yBAAyB,GAClC,iBAAiB,CAUnB;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,oBAAoB,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,eAAe,EAAE,GAAG,IAAI,CAUhG;AAwBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,+BAA+B,CAC7C,SAAS,EAAE,eAAe,EAAE,EAC5B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,wBAAwB,CAqD1B;AAED,+EAA+E;AAC/E,MAAM,MAAM,sBAAsB,GAChC;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEvF;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,yBAAyB,EACnC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,SAAS,EAAE,eAAe,EAAE,GAC3B,sBAAsB,CAkCxB;AAgBD;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,4BAA4B,CAAC;AAEtE;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,qBAAqB,GAAG,IAAI,CAW9B;AAYD;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,qBAAqB,EAC7B,SAAS,EAAE,MAAM,GAChB,wBAAwB,CA+B1B;AAED;;;;;;GAMG;AACH,wBAAgB,iCAAiC,CAAC,QAAQ,EAAE,yBAAyB,GAAG,MAAM,CAG7F"}

package/dist/elicitation.js

@@ -0,0 +1,312 @@
+import { randomUUID } from "node:crypto";
+/**
+ * Convert an MCP elicitation request (from the SDK's `onElicitation` callback)
+ * into an ACP `CreateElicitationRequest`. Returns `null` when the request can't
+ * be represented (e.g. a url-mode request with no url).
+ */
+export function mcpElicitationToCreateRequest(request, sessionId) {
+    if (request.mode === "url") {
+        if (!request.url) {
+            return null;
+        }
+        return {
+            mode: "url",
+            sessionId,
+            message: request.message,
+            url: request.url,
+            // URL elicitations need a stable id so the client can correlate the
+            // later `session/complete_elicitation` notification. MCP servers usually
+            // provide one; fall back to a generated id if not.
+            elicitationId: request.elicitationId ?? randomUUID(),
+        };
+    }
+    // Form mode (the default). The MCP `requestedSchema` is already a JSON Schema
+    // with primitive-typed properties, which is structurally what ACP expects.
+    return {
+        mode: "form",
+        sessionId,
+        message: request.message,
+        requestedSchema: normalizeElicitationSchema(request.requestedSchema),
+    };
+}
+/** A wire value allowed in elicitation form content. */
+function isElicitationContentValue(value) {
+    return (typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean" ||
+        (Array.isArray(value) && value.every((item) => typeof item === "string")));
+}
+/**
+ * Content of an accepted elicitation response.
+ *
+ * The response union includes a custom/future-action variant whose `action` is
+ * plain `string`, so a positive `=== "accept"` check can never narrow it away
+ * and `content` reads as `unknown`. Rather than asserting which union member
+ * this is, validate the values: the SDK's own wire validation has the same
+ * blind spot (an accept response with malformed content parses via the
+ * catch-all variant), so ill-typed values are dropped here either way.
+ */
+function acceptedElicitationContent(response) {
+    if (response.action !== "accept") {
+        return {};
+    }
+    const { content } = response;
+    if (!content || typeof content !== "object") {
+        return {};
+    }
+    const validated = {};
+    for (const [key, value] of Object.entries(content)) {
+        if (isElicitationContentValue(value)) {
+            validated[key] = value;
+        }
+    }
+    return validated;
+}
+/**
+ * Map an ACP elicitation response back to the MCP `ElicitResult` the SDK expects
+ * to hand back to the requesting server.
+ */
+export function createElicitationResponseToElicitResult(response) {
+    switch (response.action) {
+        case "accept":
+            return { action: "accept", content: acceptedElicitationContent(response) };
+        case "decline":
+            return { action: "decline" };
+        case "cancel":
+        default:
+            return { action: "cancel" };
+    }
+}
+/**
+ * Pull the well-formed questions out of an AskUserQuestion tool input. Returns
+ * `null` when there are no usable questions — including the case where every
+ * entry is malformed and filtering leaves an empty list — so callers can treat
+ * "nothing to ask" uniformly.
+ */
+export function extractAskUserQuestions(input) {
+    const questions = input.questions;
+    if (!Array.isArray(questions)) {
+        return null;
+    }
+    const valid = questions.filter((q) => !!q && typeof q.question === "string" && Array.isArray(q.options) && q.options.length > 0);
+    return valid.length > 0 ? valid : null;
+}
+/** Stable form-field key for the question at the given index. */
+function questionFieldKey(index) {
+    return `question_${index}`;
+}
+/**
+ * Form-field key for the per-question free-text "custom answer" field that sits
+ * alongside `question_<n>`. Mirrors the first-party clients, where every
+ * question carries its own "Other" box rather than one form-level field.
+ */
+function questionCustomFieldKey(index) {
+    return `question_${index}_custom`;
+}
+/**
+ * `_meta` key under which a bridged enum option carries its `preview`, the one
+ * option field ACP's `EnumOption` still has no slot for (descriptions are
+ * first-class as of schema 1.19). Namespaced like the agent's other `_meta`
+ * extensions (`_claude/...`).
+ */
+const OPTION_META_KEY = "_claude/askUserQuestionOption";
+/**
+ * Render the AskUserQuestion tool's questions as an ACP form elicitation.
+ *
+ * Fields are keyed by a short stable id (`question_<n>`) rather than the full
+ * question text, so the question text appears in exactly one place per field.
+ * Single-select questions use a titled `oneOf` enum; multi-select questions use
+ * an array with a titled `anyOf` item enum. The enum `const` is always the
+ * option label, since that is what the tool records as the answer; an option's
+ * secondary text travels in the enum option's own `description` field.
+ *
+ * Each question is followed by its own optional free-text "custom answer" field
+ * (`question_<n>_custom`), mirroring the CLI's per-question "Other" box: the
+ * user can type their own answer instead of picking an option, scoped to that
+ * specific question. Nothing is marked required, so the user can also just skip
+ * — matching the built-in tool, which always offers Skip + a free-text box.
+ */
+export function askUserQuestionsToCreateRequest(questions, sessionId, toolCallId) {
+    const single = questions.length === 1;
+    const properties = {};
+    questions.forEach((question, index) => {
+        const options = question.options.map((option) => {
+            const enumOption = {
+                const: option.label,
+                title: option.label,
+            };
+            if (option.description) {
+                enumOption.description = option.description;
+            }
+            // The SDK option's `preview` (mockups, code snippets, comparisons shown
+            // on focus) still has no structural slot in `EnumOption`, so forward it
+            // under ACP's reserved `_meta` extension point for clients that render it.
+            if (option.preview) {
+                enumOption._meta = { [OPTION_META_KEY]: { preview: option.preview } };
+            }
+            return enumOption;
+        });
+        // For a single question the prompt is carried by `message`, so we don't
+        // repeat it in the field description. With multiple questions each field
+        // needs its own question text.
+        const description = single ? undefined : question.question;
+        const title = question.header || undefined;
+        properties[questionFieldKey(index)] = question.multiSelect
+            ? { type: "array", title, description, items: { anyOf: options } }
+            : { type: "string", title, description, oneOf: options };
+        properties[questionCustomFieldKey(index)] = {
+            type: "string",
+            title: "Other",
+            description: "Type your own answer instead of choosing an option above (optional).",
+        };
+    });
+    const requestedSchema = {
+        type: "object",
+        properties,
+    };
+    const message = single ? questions[0].question : "Please answer the following questions.";
+    return {
+        mode: "form",
+        sessionId,
+        ...(toolCallId ? { toolCallId } : {}),
+        message,
+        requestedSchema,
+    };
+}
+/**
+ * Fold an ACP elicitation response into the AskUserQuestion tool's input.
+ *
+ * Selected labels are read back from the indexed form fields and written into
+ * `answers` as a `{ [questionText]: label }` map (comma-joining multi-selects)
+ * — the key shape the tool's own `call()` reads. A non-empty per-question
+ * custom-answer field (`question_<n>_custom`) takes precedence over that
+ * question's selection, since the user typed their own answer instead of
+ * picking one. Decline yields empty answers (the model is told the user skipped
+ * rather than the turn aborting); cancel — and any custom/future action we
+ * don't understand — aborts the tool call.
+ */
+export function applyAskElicitationResponse(response, toolInput, questions) {
+    if (response.action === "decline") {
+        return { action: "answered", updatedInput: { ...toolInput, answers: {} } };
+    }
+    if (response.action !== "accept") {
+        return { action: "cancel" };
+    }
+    const content = acceptedElicitationContent(response);
+    // Typed against the tool's own output schema so the answer/response shapes
+    // stay in sync with what the built-in tool's call() expects to read back.
+    const answers = {};
+    questions.forEach((question, index) => {
+        // A typed custom answer wins over the selection: the user chose to write
+        // their own answer for this question instead of picking an option.
+        const custom = content[questionCustomFieldKey(index)];
+        if (typeof custom === "string" && custom.trim() !== "") {
+            answers[question.question] = custom.trim();
+            return;
+        }
+        const value = content[questionFieldKey(index)];
+        if (value === undefined || value === null) {
+            return;
+        }
+        const text = Array.isArray(value) ? value.join(", ") : String(value);
+        if (text === "") {
+            return;
+        }
+        answers[question.question] = text;
+    });
+    return { action: "answered", updatedInput: { ...toolInput, answers } };
+}
+/**
+ * Coerce an arbitrary MCP `requestedSchema` into an ACP `ElicitationSchema`.
+ * The two are structurally compatible JSON Schemas; we just guarantee the
+ * `type: "object"` discriminator is present.
+ */
+function normalizeElicitationSchema(schema) {
+    if (!schema || typeof schema !== "object") {
+        return { type: "object", properties: {} };
+    }
+    return { ...schema, type: "object" };
+}
+/**
+ * The `request_user_dialog` kind the CLI emits when a model refusal has a
+ * fallback available but needs user consent before retrying (e.g. Claude Fable
+ * declining a request with Opus available as the fallback). Declaring this
+ * kind in `supportedDialogKinds` is the opt-in: the CLI fails closed and never
+ * emits an undeclared kind — the flow degrades to the classic refusal error
+ * ending the turn.
+ */
+export const REFUSAL_FALLBACK_DIALOG_KIND = "refusal_fallback_prompt";
+/**
+ * Validate the opaque dialog payload into a {@link RefusalFallbackPrompt}.
+ * Returns `null` when the required fields are missing or mistyped (a newer CLI
+ * may reshape the payload), so the caller can cancel the dialog and let the
+ * CLI apply its default behavior instead of rendering something misleading.
+ */
+export function extractRefusalFallbackPrompt(payload) {
+    const { originalModel, fallbackModel, apiRefusalCategory, guidanceText } = payload;
+    if (typeof originalModel !== "string" || typeof fallbackModel !== "string") {
+        return null;
+    }
+    return {
+        originalModel,
+        fallbackModel,
+        apiRefusalCategory: typeof apiRefusalCategory === "string" ? apiRefusalCategory : null,
+        ...(typeof guidanceText === "string" && guidanceText ? { guidanceText } : {}),
+    };
+}
+/** Form-field key carrying the user's choice in the refusal-fallback form. */
+const REFUSAL_FALLBACK_CHOICE_KEY = "choice";
+/** Wire values of the dialog's result enum (CLI schema). `edit_prompt` is
+ *  deliberately not offered: in the CLI it prefills the composer with the
+ *  refused prompt for edit-and-retry, and ACP has no composer-prefill surface
+ *  — the user can simply edit and resend on their own. */
+const RETRY_FALLBACK_RESULT = "retry_fallback";
+const KEEP_REFUSAL_RESULT = "cancelled";
+/**
+ * Render the refusal-fallback consent prompt as an ACP form elicitation: a
+ * single-select between retrying on the fallback model and keeping the
+ * refusal. The enum `const`s are the dialog's wire result values, so the
+ * response maps back without a translation table.
+ */
+export function refusalFallbackToCreateRequest(prompt, sessionId) {
+    const category = prompt.apiRefusalCategory ? ` (${prompt.apiRefusalCategory})` : "";
+    const guidance = prompt.guidanceText ? `\n\n${prompt.guidanceText}` : "";
+    return {
+        mode: "form",
+        sessionId,
+        message: `${prompt.originalModel} declined this request${category}. ` +
+            `Retry with ${prompt.fallbackModel}?` +
+            guidance,
+        requestedSchema: {
+            type: "object",
+            properties: {
+                [REFUSAL_FALLBACK_CHOICE_KEY]: {
+                    type: "string",
+                    oneOf: [
+                        {
+                            const: RETRY_FALLBACK_RESULT,
+                            title: `Retry with ${prompt.fallbackModel}`,
+                            description: `The session continues on ${prompt.fallbackModel}.`,
+                        },
+                        {
+                            const: KEEP_REFUSAL_RESULT,
+                            title: "Keep the refusal",
+                            description: "You can send a new message.",
+                        },
+                    ],
+                },
+            },
+        },
+    };
+}
+/**
+ * Map the elicitation response back to the dialog's result enum. Only an
+ * explicit accept-with-retry resolves to `retry_fallback`; decline, cancel, a
+ * skipped field, or an unrecognized value all keep the refusal — the dialog's
+ * own default — so a dismissed or half-filled form can never trigger a model
+ * switch the user didn't ask for.
+ */
+export function refusalFallbackResultFromResponse(response) {
+    const choice = acceptedElicitationContent(response)[REFUSAL_FALLBACK_CHOICE_KEY];
+    return choice === RETRY_FALLBACK_RESULT ? RETRY_FALLBACK_RESULT : KEEP_REFUSAL_RESULT;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}