@alas-ide/codex-acp 2.5.0-alas.1 → 2.5.0-alas.3

package/README.md

@@ -17,6 +17,7 @@ Use [OpenAI Codex](https://github.com/openai/codex) from [Agent Client Protocol]
 - For AIR, one tool call shape with each fact in one field, as the [tool call contract](docs/air-extensions.md#tool-call-contract) defines. Other clients keep the earlier fields.
 - [Native ACP subagent sessions](docs/subagent-sessions.md) (after capability negotiation) with separate child histories and root-routed permissions; a legacy tool-call fallback otherwise.
 - Mid-turn input through the [_session/steering extension](docs/steering.md), with an opt-in host-owned fallback when no turn can accept it.
+- [Async Codex questions](docs/async-questions.md) as non-blocking form elicitations, with answers steered into the turn that asked them.
 - [Background terminal tasks](docs/air-extensions.md#async-tasks) in AIR, with task status and targeted stop support after capability negotiation.
 - Session-scoped long-running goals in AIR through the [goal extension](docs/air-extensions.md#goal).
 - Typed warnings and errors through the opt-in [AIR session failure extension](docs/air-extensions.md#session-failure).

package/dist/index.js

@@ -32389,8 +32389,19 @@ var AcpV2Connection = class {
       return toV1RequestPermissionResponse(response);
     }, options?.cancellationSignal);
   }
-  /** Request-scoped login elicitations and idle background elicitations never change state. */
-  async createElicitation(request, options) {
+  /**
+   * Sends `elicitation/create`. Request-scoped login elicitations and idle background elicitations never change
+   * the session state.
+   *
+   * @param request The elicitation to show.
+   * @param options Request options, such as the signal that cancels the request.
+   * @param interaction.userAction Whether the agent waits for the answer, `true` by default. While such an
+   *     elicitation is open in a running turn, the session reports `requires_action` whenever none of its items
+   *     is in progress. Pass `false` for a question the agent keeps working through, so the session state is left
+   *     as it is.
+   */
+  async createElicitation(request, options, interaction = {}) {
+    const userAction = interaction.userAction ?? true;
     const sendRequest = async () => {
       const response = await this.client.request(
         methods2.client.elicitation.create,
@@ -32400,7 +32411,7 @@ var AcpV2Connection = class {
       return toV1CreateElicitationResponse(response);
     };
     const sessionId = elicitationSessionId(request);
-    if (sessionId === void 0) {
+    if (sessionId === void 0 || !userAction) {
       return sendRequest();
     }
     const toolCallId = "toolCallId" in request && typeof request.toolCallId === "string" ? request.toolCallId : void 0;
@@ -37649,12 +37660,16 @@ ${params.turnId}`;
     }
     return this.createAgentMessageText(citations.push(event.delta), event.itemId, event.threadId);
   }
-  /** Sends the text a file citation held back, once the message is complete. */
-  flushAgentMessageText(itemId, threadId) {
+  /**
+   * Sends the text a file citation held back, once the message is complete. A message that
+   * arrives whole, without deltas (an async question, for one), is sent in full.
+   */
+  flushAgentMessageText(item, threadId) {
     const streams = this.streamsFor(threadId);
-    const rest = streams.agentMessageCitations.get(itemId)?.flush() ?? "";
-    streams.agentMessageCitations.delete(itemId);
-    return this.createAgentMessageText(rest, itemId, threadId);
+    const citations = streams.agentMessageCitations.get(item.id);
+    streams.agentMessageCitations.delete(item.id);
+    const text = citations ? citations.flush() : renderFileCitations(item.text, this.sessionState.cwd);
+    return this.createAgentMessageText(text, item.id, threadId);
   }
   createAgentMessageText(text, itemId, threadId) {
     if (text.length === 0) return null;
@@ -37809,7 +37824,7 @@ ${event.details}` : event.summary;
         return this.renderer.render(this.subagents.legacyCollaborationCompleted(event.item));
       case "agentMessage":
         this.rememberAgentMessagePhase(event.item, event.threadId);
-        return this.flushAgentMessageText(event.item.id, event.threadId);
+        return this.flushAgentMessageText(event.item, event.threadId);
       case "plan":
         return await this.createCompletedPlanEvent(event.item);
       case "exitedReviewMode":
@@ -38989,6 +39004,119 @@ function userInputResponseValue(content, fieldId) {
   }
   return value;
 }
+function buildUserInputSchema(questions, clientCapabilities, answersRequired) {
+  const properties = {};
+  const required2 = [];
+  const questionIds = new Set(questions.map((question) => question.id));
+  const airClient = isAirClient(clientCapabilities);
+  for (const question of questions) {
+    const options = question.options ?? [];
+    const hasOptions = options.length > 0;
+    const hasOtherAnswer = question.isOther && hasOptions;
+    const base = {
+      title: question.question || question.header || question.id,
+      ...question.header ? { description: question.header } : {},
+      _meta: {
+        codex: {
+          isOther: question.isOther,
+          isSecret: question.isSecret
+        }
+      }
+    };
+    if (answersRequired) {
+      required2.push(question.id);
+    }
+    properties[question.id] = hasOptions ? {
+      ...base,
+      type: "string",
+      oneOf: [
+        ...options.map((option) => ({
+          const: option.label,
+          title: option.label,
+          ...option.description ? { description: option.description } : {}
+        })),
+        ...hasOtherAnswer && !airClient && !options.some((option) => option.label === USER_INPUT_OTHER_OPTION) ? [{
+          const: USER_INPUT_OTHER_OPTION,
+          title: USER_INPUT_OTHER_OPTION,
+          description: "Provide a different answer in the note field."
+        }] : []
+      ]
+    } : {
+      ...base,
+      type: "string"
+    };
+    if (hasOtherAnswer) {
+      const noteMeta = {
+        codex: {
+          questionId: question.id,
+          role: "user_note",
+          isSecret: question.isSecret
+        }
+      };
+      properties[userInputNoteFieldId(question.id, questionIds)] = {
+        type: "string",
+        title: "Additional answer or note",
+        _meta: airClient ? withAirMeta({ ...noteMeta, [LEGACY_AIR_CUSTOM_ANSWER_KEY]: true }, AIR_CUSTOM_ANSWER_KEY, true) : noteMeta
+      };
+    }
+  }
+  return {
+    type: "object",
+    properties,
+    ...answersRequired ? { required: required2 } : {}
+  };
+}
+function buildUserInputRequest(params, clientCapabilities) {
+  return {
+    sessionId: params.threadId,
+    toolCallId: params.itemId,
+    mode: "form",
+    message: "Codex needs your input to continue.",
+    requestedSchema: buildUserInputSchema(params.questions, clientCapabilities, true),
+    _meta: {
+      codex: {
+        autoResolutionMs: params.autoResolutionMs
+      }
+    }
+  };
+}
+function userInputAnswers(response, questions, clientCapabilities) {
+  if (!CreateElicitationResponse.isAccept(response)) {
+    return {};
+  }
+  const answers = {};
+  const content = contentRecord(response.content);
+  const questionIds = new Set(questions.map((question) => question.id));
+  const airClient = isAirClient(clientCapabilities);
+  for (const question of questions) {
+    const answerValues = [];
+    const hasOtherAnswer = question.isOther && question.options != null && question.options.length > 0;
+    const value = userInputResponseValue(content, question.id);
+    const typedAnswer = airClient && hasOtherAnswer ? typedChoiceAnswer(value, question) : void 0;
+    if (typedAnswer !== void 0) {
+      answerValues.push(USER_INPUT_OTHER_OPTION, `${USER_INPUT_NOTE_PREFIX}${typedAnswer.trim()}`);
+    } else if (value !== void 0) {
+      answerValues.push(...Array.isArray(value) ? value.map(String) : [String(value)]);
+    }
+    if (hasOtherAnswer) {
+      const note = userInputResponseValue(content, userInputNoteFieldId(question.id, questionIds));
+      if (note !== void 0) {
+        const notes = Array.isArray(note) ? note : [note];
+        answerValues.push(...notes.map((item) => `${USER_INPUT_NOTE_PREFIX}${String(item).trim()}`));
+      }
+    }
+    if (answerValues.length === 0) {
+      continue;
+    }
+    answers[question.id] = {
+      answers: answerValues
+    };
+  }
+  return answers;
+}
+function userInputAnswerText(answers) {
+  return answers.filter((answer) => answer !== USER_INPUT_OTHER_OPTION).map((answer) => answer.startsWith(USER_INPUT_NOTE_PREFIX) ? answer.slice(USER_INPUT_NOTE_PREFIX.length) : answer).filter((answer) => answer.trim().length > 0).join("\n\n");
+}
 var CodexElicitationHandler = class {
   connection;
   renderer;
@@ -39097,7 +39225,7 @@ var CodexElicitationHandler = class {
       if (response === null) {
         return { answers: {} };
       }
-      return this.convertUserInputResponse(response, params);
+      return { answers: userInputAnswers(response, params.questions, this.clientCapabilities) };
     } catch (error62) {
       logger.error("Error handling Codex user input request", error62);
       return { answers: {} };
@@ -39107,7 +39235,7 @@ var CodexElicitationHandler = class {
     return cancellationSignal ? { cancellationSignal } : void 0;
   }
   async requestUserInputElicitation(params) {
-    const request = this.buildUserInputRequest(params);
+    const request = buildUserInputRequest(params, this.clientCapabilities);
     const signal = subagentInteractionSignal(params.threadId, this.cancellationSignal);
     if (params.autoResolutionMs === null) {
       return await withSubagentUserAction(params.threadId, () => this.connection.request(
@@ -39207,77 +39335,6 @@ var CodexElicitationHandler = class {
         };
     }
   }
-  buildUserInputRequest(params) {
-    const properties = {};
-    const required2 = [];
-    const questionIds = new Set(params.questions.map((question) => question.id));
-    const airClient = isAirClient(this.clientCapabilities);
-    for (const question of params.questions) {
-      const options = question.options ?? [];
-      const hasOptions = options.length > 0;
-      const hasOtherAnswer = question.isOther && hasOptions;
-      const base = {
-        title: question.question || question.header || question.id,
-        ...question.header ? { description: question.header } : {},
-        _meta: {
-          codex: {
-            isOther: question.isOther,
-            isSecret: question.isSecret
-          }
-        }
-      };
-      required2.push(question.id);
-      properties[question.id] = hasOptions ? {
-        ...base,
-        type: "string",
-        oneOf: [
-          ...options.map((option) => ({
-            const: option.label,
-            title: option.label,
-            ...option.description ? { description: option.description } : {}
-          })),
-          ...hasOtherAnswer && !airClient && !options.some((option) => option.label === USER_INPUT_OTHER_OPTION) ? [{
-            const: USER_INPUT_OTHER_OPTION,
-            title: USER_INPUT_OTHER_OPTION,
-            description: "Provide a different answer in the note field."
-          }] : []
-        ]
-      } : {
-        ...base,
-        type: "string"
-      };
-      if (hasOtherAnswer) {
-        const noteMeta = {
-          codex: {
-            questionId: question.id,
-            role: "user_note",
-            isSecret: question.isSecret
-          }
-        };
-        properties[userInputNoteFieldId(question.id, questionIds)] = {
-          type: "string",
-          title: "Additional answer or note",
-          _meta: airClient ? withAirMeta({ ...noteMeta, [LEGACY_AIR_CUSTOM_ANSWER_KEY]: true }, AIR_CUSTOM_ANSWER_KEY, true) : noteMeta
-        };
-      }
-    }
-    return {
-      sessionId: params.threadId,
-      toolCallId: params.itemId,
-      mode: "form",
-      message: "Codex needs your input to continue.",
-      requestedSchema: {
-        type: "object",
-        properties,
-        required: required2
-      },
-      _meta: {
-        codex: {
-          autoResolutionMs: params.autoResolutionMs
-        }
-      }
-    };
-  }
   convertElicitationResponse(response, context) {
     if (CreateElicitationResponse.isAccept(response)) {
       const content = contentRecord(response.content);
@@ -39308,40 +39365,6 @@ var CodexElicitationHandler = class {
   isAllowedToolApprovalPersist(persist, persistOptions) {
     return persist === void 0 || persist === "once" || persist === "session" && persistOptions.has("session") || persist === "always" && persistOptions.has("always");
   }
-  convertUserInputResponse(response, params) {
-    if (!CreateElicitationResponse.isAccept(response)) {
-      return { answers: {} };
-    }
-    const answers = {};
-    const content = contentRecord(response.content);
-    const questionIds = new Set(params.questions.map((question) => question.id));
-    const airClient = isAirClient(this.clientCapabilities);
-    for (const question of params.questions) {
-      const answerValues = [];
-      const hasOtherAnswer = question.isOther && question.options != null && question.options.length > 0;
-      const value = userInputResponseValue(content, question.id);
-      const typedAnswer = airClient && hasOtherAnswer ? typedChoiceAnswer(value, question) : void 0;
-      if (typedAnswer !== void 0) {
-        answerValues.push(USER_INPUT_OTHER_OPTION, `${USER_INPUT_NOTE_PREFIX}${typedAnswer.trim()}`);
-      } else if (value !== void 0) {
-        answerValues.push(...Array.isArray(value) ? value.map(String) : [String(value)]);
-      }
-      if (hasOtherAnswer) {
-        const note = userInputResponseValue(content, userInputNoteFieldId(question.id, questionIds));
-        if (note !== void 0) {
-          const notes = Array.isArray(note) ? note : [note];
-          answerValues.push(...notes.map((item) => `${USER_INPUT_NOTE_PREFIX}${String(item).trim()}`));
-        }
-      }
-      if (answerValues.length === 0) {
-        continue;
-      }
-      answers[question.id] = {
-        answers: answerValues
-      };
-    }
-    return { answers };
-  }
   async publishAcceptedMcpToolApproval(sessionId, context, accepted) {
     if (!accepted || context.correlatedCallId === void 0) {
       return;
@@ -40588,7 +40611,7 @@ var package_default = {
   publishConfig: {
     access: "public"
   },
-  version: "2.5.0-alas.1",
+  version: "2.5.0-alas.3",
   description: "",
   main: "dist/index.js",
   bin: {
@@ -40666,7 +40689,7 @@ var package_default = {
   alasDownstream: {
     upstreamVersion: "2.5.0",
     upstreamCommit: "34e08970aa324a2be985f5080674d5aa91d7666f",
-    sourceCommit: "845c14e611fff5b534ecd38847d0b3dc1b69d0e6"
+    sourceCommit: "de8d4c961871fc0584ca1bd89f31a8de95066c65"
   }
 };
 
@@ -40896,9 +40919,31 @@ var CodexSubagentSubscriptions = class {
 
 // src/SessionFork.ts
 import { createHash } from "node:crypto";
+var NEUTRAL_FORK_POINT_META_KEY = "forkPoint";
+var NEUTRAL_FORK_POINT_VERSION = 1;
+function neutralForkPointCapability() {
+  return { version: NEUTRAL_FORK_POINT_VERSION, boundary: "turn" };
+}
+function clientRequestsNeutralForkPoint(capabilities) {
+  const declared = capabilities?._meta?.[NEUTRAL_FORK_POINT_META_KEY];
+  if (!isUnknownRecord(declared)) return false;
+  const version2 = declared["version"];
+  return typeof version2 === "number" && Number.isInteger(version2) && version2 >= 1;
+}
+function hasNeutralForkPoint(meta3) {
+  return meta3 != null && meta3[NEUTRAL_FORK_POINT_META_KEY] !== void 0;
+}
+function forkPointNotNegotiatedError() {
+  return RequestError.invalidParams(
+    { [NEUTRAL_FORK_POINT_META_KEY]: { reason: "notNegotiated" } },
+    "session/fork _meta.forkPoint needs initialize clientCapabilities._meta.forkPoint"
+  );
+}
 async function forkSession(request, additionalDirectories, dependencies, instructions) {
+  const forkPoint = readForkPoint(request._meta);
   await dependencies.refreshSkills(request.cwd, additionalDirectories);
-  const lastTurnId = await resolveForkTurnId(request, dependencies.codexClient);
+  const match = forkPoint ? await resolveForkPoint(request, forkPoint, dependencies.codexClient) : void 0;
+  const lastTurnId = match?.turnId;
   const sessionConfig = await dependencies.createSessionConfig(
     request.cwd,
     additionalDirectories,
@@ -40930,26 +40975,83 @@ async function forkSession(request, additionalDirectories, dependencies, instruc
     currentServiceTier: response.serviceTier ?? null,
     additionalDirectories,
     skippedMcpServers: sessionConfig.skippedMcpServers,
-    ...instructions ? { instructions } : {}
+    ...instructions ? { instructions } : {},
+    ...forkPoint?.kind === "neutral" && match ? {
+      forkPoint: {
+        boundary: "turn",
+        messageId: match.messageId,
+        turnId: match.turnId,
+        lastItemId: match.lastItemId,
+        matchedBy: match.matchedBy
+      }
+    } : {}
   };
 }
-async function resolveForkTurnId(request, codexClient) {
-  const forkPoint = readAirForkPoint(request._meta);
-  if (!forkPoint) return void 0;
+function readForkPoint(meta3) {
+  if (hasNeutralForkPoint(meta3)) return { kind: "neutral", ...readNeutralForkPoint(meta3[NEUTRAL_FORK_POINT_META_KEY]) };
+  const air = readAirForkPoint(meta3);
+  return air ? { kind: "air", ...air } : void 0;
+}
+async function resolveForkPoint(request, forkPoint, codexClient) {
   const history = await codexClient.threadReadWithHistory(request.sessionId);
-  const candidateIds = airForkMessageIdCandidates(forkPoint.messageId);
-  const itemTurnId = candidateIds.map((candidateId) => history.thread.turns.find((turn) => turn.items.some((item) => item.id === candidateId))?.id).find((turnId) => turnId !== void 0);
-  if (itemTurnId) return itemTurnId;
+  const turns = history.thread.turns;
+  const matchById = (candidateId) => {
+    const turn = turns.find((turn2) => turn2.items.some((item) => item.id === candidateId));
+    return turn ? toMatch(turn, candidateId, "id") : void 0;
+  };
+  const candidateIds = forkPoint.kind === "air" ? airForkMessageIdCandidates(forkPoint.messageId) : [forkPoint.messageId];
+  const idMatch = candidateIds.map(matchById).find((match) => match !== void 0);
+  if (idMatch) return idMatch;
   if (forkPoint.messageFingerprint) {
-    const matchingTurns = history.thread.turns.flatMap((turn) => turn.items.filter((item) => item.type === "agentMessage" && fingerprintAgentMessage(item.text) === forkPoint.messageFingerprint).map(() => turn.id));
-    const fingerprintTurnId = matchingTurns[forkPoint.messageOccurrence - 1];
-    if (fingerprintTurnId) return fingerprintTurnId;
+    const renderCwd = history.thread.cwd ?? request.cwd;
+    const clientText = forkPoint.kind === "neutral" ? (text) => renderFileCitations(text, renderCwd) : (text) => text;
+    const matches = turns.flatMap((turn) => turn.items.filter((item) => item.type === "agentMessage" && fingerprintAgentMessage(clientText(item.text)) === forkPoint.messageFingerprint).map((item) => toMatch(turn, item.id, "fingerprint")));
+    const fingerprintMatch = matches[forkPoint.messageOccurrence - 1];
+    if (fingerprintMatch) return fingerprintMatch;
+  }
+  if (forkPoint.kind === "neutral") {
+    throw RequestError.invalidParams(
+      { [NEUTRAL_FORK_POINT_META_KEY]: { messageId: forkPoint.messageId, reason: "notFound" } },
+      `Fork point message ${forkPoint.messageId} was not found in session ${request.sessionId}`
+    );
   }
   throw RequestError.invalidParams(
     { messageId: forkPoint.messageId },
     `Fork point message ${forkPoint.messageId} was not found in session ${request.sessionId}`
   );
 }
+function toMatch(turn, messageId, matchedBy) {
+  return { messageId, turnId: turn.id, lastItemId: turn.items.at(-1).id, matchedBy };
+}
+function readNeutralForkPoint(forkPoint) {
+  const invalid = (field, message) => RequestError.invalidParams(
+    { [NEUTRAL_FORK_POINT_META_KEY]: { field } },
+    `session/fork _meta.forkPoint: ${message}`
+  );
+  if (!isUnknownRecord(forkPoint)) throw invalid(NEUTRAL_FORK_POINT_META_KEY, "must be an object");
+  const version2 = forkPoint["version"];
+  if (version2 !== void 0 && version2 !== NEUTRAL_FORK_POINT_VERSION) {
+    throw invalid("version", `version must be ${NEUTRAL_FORK_POINT_VERSION} when present`);
+  }
+  const messageId = forkPoint["messageId"];
+  if (typeof messageId !== "string" || messageId.trim().length === 0) {
+    throw invalid("messageId", "messageId must be a non-empty string");
+  }
+  const messageFingerprint = forkPoint["messageFingerprint"];
+  if (messageFingerprint !== void 0 && (typeof messageFingerprint !== "string" || !SHA256_FINGERPRINT.test(messageFingerprint))) {
+    throw invalid("messageFingerprint", "messageFingerprint must be sha256: and 64 lowercase hex digits");
+  }
+  const messageOccurrence = forkPoint["messageOccurrence"] ?? 1;
+  if (!Number.isSafeInteger(messageOccurrence) || messageOccurrence < 1) {
+    throw invalid("messageOccurrence", "messageOccurrence must be a positive integer");
+  }
+  return {
+    messageId: messageId.trim(),
+    ...typeof messageFingerprint === "string" && { messageFingerprint },
+    messageOccurrence
+  };
+}
+var SHA256_FINGERPRINT = /^sha256:[0-9a-f]{64}$/;
 function readAirForkPoint(meta3) {
   const jetbrains = meta3?.["jetbrains"];
   if (!isUnknownRecord(jetbrains)) return void 0;
@@ -40962,7 +41064,7 @@ function readAirForkPoint(meta3) {
     throw RequestError.invalidParams(void 0, "AIR fork messageId must be a non-empty string");
   }
   const messageFingerprint = fork["messageFingerprint"];
-  if (messageFingerprint !== void 0 && (typeof messageFingerprint !== "string" || !/^sha256:[0-9a-f]{64}$/.test(messageFingerprint))) {
+  if (messageFingerprint !== void 0 && (typeof messageFingerprint !== "string" || !SHA256_FINGERPRINT.test(messageFingerprint))) {
     throw RequestError.invalidParams(void 0, "AIR fork messageFingerprint must be a SHA-256 fingerprint");
   }
   const messageOccurrence = fork["messageOccurrence"] ?? 1;
@@ -48951,6 +49053,198 @@ function isJetBrains2026_1Client(clientInfo) {
   return (isIntelliJPlatform || isJetBrainsClient) && clientInfo.version.startsWith("2026.1");
 }
 
+// src/CodexAsyncQuestions.ts
+import { randomUUID as randomUUID5 } from "node:crypto";
+var TOOL_NAME = "request_user_input_async";
+var REPLY_START = "<send_user_message_question_reply>";
+var REPLY_END = "</send_user_message_question_reply>";
+var MAX_REPLY_FIELD_LENGTH = 512;
+function asyncQuestionItemId(messageId, index) {
+  return JSON.stringify([TOOL_NAME, messageId, index]);
+}
+function formatAsyncQuestionReply(replies) {
+  const bounded = replies.map((reply) => ({
+    ...reply,
+    question: [...reply.question].slice(0, MAX_REPLY_FIELD_LENGTH).join("").replace(/[\r\n]/g, " ")
+  }));
+  if (bounded.some((reply) => reply.questionItemId.length > MAX_REPLY_FIELD_LENGTH)) {
+    return displayReplies(bounded);
+  }
+  const body = bounded.map(({ answer, question, questionItemId }) => ({ answer, question, questionItemId }));
+  return `${REPLY_START}
+${JSON.stringify(body)}
+${REPLY_END}`;
+}
+function parseAsyncQuestionReply(text) {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith(REPLY_START) || !trimmed.endsWith(REPLY_END)) return null;
+  let body;
+  try {
+    body = JSON.parse(trimmed.slice(REPLY_START.length, trimmed.length - REPLY_END.length));
+  } catch {
+    return null;
+  }
+  const replies = Array.isArray(body) ? body : [body];
+  if (replies.length === 0 || !replies.every(isReply)) return null;
+  return replies.map(({ questionItemId, question, answer }) => ({ questionItemId, question, answer }));
+}
+function renderAsyncQuestionReply(text) {
+  const replies = parseAsyncQuestionReply(text);
+  return replies === null ? null : displayReplies(replies);
+}
+function displayReplies(replies) {
+  return replies.map((reply) => `> ${reply.question}
+
+${reply.answer}`).join("\n\n");
+}
+function isReply(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const reply = value;
+  return typeof reply["questionItemId"] === "string" && typeof reply["question"] === "string" && typeof reply["answer"] === "string";
+}
+var AsyncQuestionClient = class {
+  /**
+   * @param sessionId The session that the questions belong to.
+   * @param connection The connection to the ACP client.
+   * @param clientCapabilities The capabilities that the ACP client declared.
+   * @param codexAcpClient Returns the current Codex client, which changes when the app-server restarts.
+   */
+  constructor(sessionId, connection, clientCapabilities, codexAcpClient) {
+    this.sessionId = sessionId;
+    this.connection = connection;
+    this.clientCapabilities = clientCapabilities;
+    this.codexAcpClient = codexAcpClient;
+  }
+  sessionId;
+  connection;
+  clientCapabilities;
+  codexAcpClient;
+  /** Sends the elicitation without marking the session as waiting for the user. */
+  createElicitation(request, signal) {
+    const v2 = AcpV2Connection.of(this.connection);
+    return v2 !== null ? v2.createElicitation(request, { cancellationSignal: signal }, { userAction: false }) : this.connection.request(methods.client.elicitation.create, request, { cancellationSignal: signal });
+  }
+  /** Steers the text into the turn; rejects if that turn is no longer running. */
+  async steer(turnId, text) {
+    await this.codexAcpClient().steerTurn({
+      threadId: this.sessionId,
+      turnId,
+      prompt: [{ type: "text", text }],
+      clientUserMessageId: randomUUID5()
+    });
+  }
+  /** Tells the user that an answer was not sent, if the client supports notices. */
+  async reportDroppedAnswer() {
+    if (!clientSupportsNotices(this.clientCapabilities)) return;
+    await this.connection.notify(methods.client.session.update, {
+      sessionId: this.sessionId,
+      update: createSessionNotice(
+        "warning",
+        "Answer not sent",
+        "Codex finished before your answer arrived. Send it as a new message if it still matters."
+      )
+    });
+  }
+};
+var AsyncQuestionElicitations = class {
+  constructor(sessionId, clientCapabilities, client) {
+    this.sessionId = sessionId;
+    this.clientCapabilities = clientCapabilities;
+    this.client = client;
+  }
+  sessionId;
+  clientCapabilities;
+  client;
+  // The running turns that asked a question, each with the signal that cancels its questions.
+  turns = /* @__PURE__ */ new Map();
+  /** Asks the questions of a completed async message and cancels them when their turn ends; never waits. */
+  handleNotification(notification) {
+    switch (notification.method) {
+      case "item/completed": {
+        const { threadId, turnId, item } = notification.params;
+        if (threadId === this.sessionId && item.type === "agentMessage" && item.delivery === "async" && (item.questions?.length ?? 0) > 0) {
+          this.ask(turnId, item);
+        }
+        return;
+      }
+      case "turn/completed":
+        if (notification.params.threadId === this.sessionId) {
+          this.endTurn(notification.params.turn.id);
+        }
+        return;
+      default:
+        return;
+    }
+  }
+  /** Cancels every open question, when the session closes or its app-server is gone. */
+  dispose() {
+    for (const turnId of [...this.turns.keys()]) {
+      this.endTurn(turnId);
+    }
+  }
+  endTurn(turnId) {
+    this.turns.get(turnId)?.abort();
+    this.turns.delete(turnId);
+  }
+  ask(turnId, message) {
+    if (!clientSupportsFormElicitation(this.clientCapabilities)) return;
+    let turn = this.turns.get(turnId);
+    if (turn === void 0) {
+      turn = new AbortController();
+      this.turns.set(turnId, turn);
+    }
+    const questions = formQuestions(message);
+    const request = {
+      sessionId: this.sessionId,
+      mode: "form",
+      message: "Codex keeps working while you answer. An answer sent after it finishes is not delivered.",
+      // Questions are answered independently, as in Codex.
+      requestedSchema: buildUserInputSchema(questions, this.clientCapabilities, false),
+      _meta: { codex: { delivery: "async" } }
+    };
+    void this.client.createElicitation(request, turn.signal).then(
+      (response) => this.answer(turnId, message, questions, response).catch((error62) => logger.error("Failed to deliver an async question answer", error62)),
+      (error62) => logger.log("Async question closed without an answer", { sessionId: this.sessionId, turnId, error: error62 })
+    );
+  }
+  async answer(turnId, message, questions, response) {
+    const answers = userInputAnswers(response, questions, this.clientCapabilities);
+    const replies = questions.flatMap((question, index) => {
+      const answer = userInputAnswerText(answers[question.id]?.answers ?? []);
+      return answer.length === 0 ? [] : [{
+        questionItemId: asyncQuestionItemId(message.id, index),
+        question: question.question,
+        answer
+      }];
+    });
+    if (replies.length === 0) return;
+    if (this.turns.has(turnId)) {
+      try {
+        await this.client.steer(turnId, formatAsyncQuestionReply(replies));
+        return;
+      } catch (error62) {
+        logger.log("Async question answer was not steered into its turn", { sessionId: this.sessionId, turnId, error: error62 });
+      }
+    }
+    logger.log("Dropped an async question answer: its turn has ended", { sessionId: this.sessionId, turnId });
+    await this.client.reportDroppedAnswer();
+  }
+};
+function formQuestions(message) {
+  return (message.questions ?? []).map((question, index) => {
+    const options = question.options ?? [];
+    return {
+      id: `question_${index}`,
+      header: "",
+      question: question.title,
+      // Codex always accepts an own answer.
+      isOther: options.length > 0,
+      isSecret: false,
+      options: options.length > 0 ? options.map((label) => ({ label, description: "" })) : null
+    };
+  });
+}
+
 // src/subagents/AcpSubagents.ts
 function subagentProtocol(capabilities, version2 = 1) {
   const subagents = capabilities?.subagents;
@@ -48979,7 +49273,7 @@ var SubagentInteractionHandlers = class {
 };
 
 // src/CodexAcpServer.ts
-import { randomUUID as randomUUID6 } from "node:crypto";
+import { randomUUID as randomUUID7 } from "node:crypto";
 
 // src/TitleGenerator.ts
 var TITLE_MODEL = "gpt-5.6-luna";
@@ -50067,7 +50361,7 @@ function remember(cache, key, value) {
 }
 
 // src/SessionListSubscriptions.ts
-import { randomUUID as randomUUID5 } from "node:crypto";
+import { randomUUID as randomUUID6 } from "node:crypto";
 import path14 from "node:path";
 
 // src/CodexHomeWatcher.ts
@@ -50475,7 +50769,7 @@ var SessionListSubscriptions = class {
       this.startWatching();
       created.ready = this.makeReady(created);
     }
-    const subscription = { id: randomUUID5(), group, sent: /* @__PURE__ */ new Map(), ready: false, held: null, readyTimer: null, startedSecond: null, epoch: ++this.epoch };
+    const subscription = { id: randomUUID6(), group, sent: /* @__PURE__ */ new Map(), ready: false, held: null, readyTimer: null, startedSecond: null, epoch: ++this.epoch };
     this.subscriptions.set(subscription.id, subscription);
     group.subscriptions.add(subscription);
     this.startWatching();
@@ -51846,6 +52140,8 @@ var CodexAcpServer = class {
   /** The capability choices of the client for tool call and plan reports. */
   capabilities;
   booleanConfigOptionsSupported;
+  /** Whether the client opted into the client-neutral `session/fork` `_meta.forkPoint`. */
+  neutralForkPointSupported = false;
   /** Last `authStatus` pushed to the client; used to suppress duplicates. */
   currentAuthStatus;
   /**
@@ -51867,6 +52163,8 @@ var CodexAcpServer = class {
   /** Tail of the per-session turn-start FIFO; see `acquireTurnStartReservation`. */
   turnStartQueueTail;
   steeringQueues;
+  /** The async questions of each session, shown while the turn that asked them runs. */
+  asyncQuestions = /* @__PURE__ */ new Map();
   /**
    * Steers awaiting their `userMessage` landing, keyed by the minted `clientUserMessageId`
    * passed to `turn/steer`. Used only to show a v2 live `user_message` when a steer injected
@@ -51959,7 +52257,7 @@ var CodexAcpServer = class {
     this.captureStderr();
     this.getExitCode = getExitCode ?? (() => this.codexProcessState?.connection.process.exitCode ?? null);
     this.getRecentStderr = getRecentStderr ?? (() => this.codexProcessState?.stderr ?? "");
-    this.sessionFailureEpoch = randomUUID6();
+    this.sessionFailureEpoch = randomUUID7();
     this.clientInfo = null;
     this.clientCapabilities = null;
     this.capabilities = ClientCapabilities.DEFAULT;
@@ -52106,6 +52404,7 @@ var CodexAcpServer = class {
     if (appServer) await appServer;
     this.reportingConnection.reports.compareMeta = this.capabilities.airToolCallContract;
     this.booleanConfigOptionsSupported = clientSupportsBooleanConfigOptions(_params.clientCapabilities);
+    this.neutralForkPointSupported = clientRequestsNeutralForkPoint(_params.clientCapabilities);
     this.sessionIndex.configure(_params.clientCapabilities);
     this.hookReview.configure(_params.clientCapabilities?._meta?.["codexHooks"], this.capabilities.airClient);
     await this.runWithProcessCheck(() => this.codexAcpClient.initialize(_params));
@@ -52165,6 +52464,7 @@ var CodexAcpServer = class {
     if (appServer) await appServer;
     this.reportingConnection.reports.compareMeta = this.capabilities.airToolCallContract;
     this.booleanConfigOptionsSupported = true;
+    this.neutralForkPointSupported = clientRequestsNeutralForkPoint(clientCapabilities);
     this.sessionIndex.configure(clientCapabilities, { neutral: false });
     await this.runWithProcessCheck(() => this.codexAcpClient.initialize({ clientInfo: params.info }));
     this.sessionIndex.observe(this.codexAcpClient);
@@ -52249,6 +52549,10 @@ var CodexAcpServer = class {
         "async-tasks": asyncTaskCapability()
       } : {},
       ...this.hookReview.enabled ? { codexHooks: { version: 1, reviewToken: true } } : {},
+      // The client-neutral fork point, see `docs/air-extensions.md`.
+      ...this.neutralForkPointSupported ? {
+        [NEUTRAL_FORK_POINT_META_KEY]: neutralForkPointCapability()
+      } : {},
       // The session index for a client that opted in without AIR, see `docs/air-extensions.md`.
       ...neutralSessionIndex ? {
         [NEUTRAL_SESSION_INDEX_META_KEY]: neutralSessionIndex
@@ -52542,7 +52846,7 @@ You have been logged out. Please try again.`);
     this.sessionGenerations.set(sessionId, generation);
     return generation;
   }
-  async tryCreateSession(request, operation = "sessionId" in request ? "resume" : "new") {
+  async tryCreateSession(request, operation = "sessionId" in request ? "resume" : "new", onForked) {
     clientSystemPromptText(request.systemPrompt);
     const existingSessionRequest = request;
     const previousInstructions = "sessionId" in request ? this.sessions.get(request.sessionId)?.instructions : void 0;
@@ -52593,6 +52897,7 @@ You have been logged out. Please try again.`);
           previousInstructions
         );
       });
+      onForked?.(sessionMetadata);
     } else {
       logger.log(`Create new session...`);
       sessionMetadata = await this.runWithProcessCheck(() => {
@@ -53161,6 +53466,9 @@ You have been logged out. Please try again.`);
   async forkSession(params) {
     params = this.withV1SessionInstructionAppend(params);
     clientSystemPromptText(params.systemPrompt);
+    if (hasNeutralForkPoint(params._meta) && !this.neutralForkPointSupported) {
+      throw forkPointNotNegotiatedError();
+    }
     this.assertInstructionsReady(params.sessionId);
     return this.hookReview.run(
       params.cwd,
@@ -53176,12 +53484,16 @@ You have been logged out. Please try again.`);
     if (appServer) await appServer;
     logger.log("Forking session...", { sessionId: params.sessionId });
     try {
-      const [sessionId, , modeState] = await this.tryCreateSession(params, "fork");
+      let forkPoint;
+      const [sessionId, , modeState] = await this.tryCreateSession(params, "fork", (metadata) => {
+        forkPoint = metadata.forkPoint;
+      });
       logger.log("Session forked", { sourceSessionId: params.sessionId, sessionId });
       return {
         sessionId,
         modes: modeState,
-        ...this.createSessionConfigOptionsResponse(this.getSessionState(sessionId))
+        ...this.createSessionConfigOptionsResponse(this.getSessionState(sessionId)),
+        ...forkPoint ? { _meta: { [NEUTRAL_FORK_POINT_META_KEY]: forkPoint } } : {}
       };
     } catch (e) {
       const error62 = e instanceof Error ? e : new Error(String(e));
@@ -53192,10 +53504,11 @@ You have been logged out. Please try again.`);
   async forkSessionV2(params) {
     const { systemPrompt, ...rest } = params;
     const request = { ...rest, systemPrompt: toV1SystemPrompt(systemPrompt) };
-    const { sessionId } = await this.forkSession(request);
+    const { sessionId, _meta } = await this.forkSession(request);
     return {
       sessionId,
-      ...this.createSessionSetupResponseV2(this.getSessionState(sessionId))
+      ...this.createSessionSetupResponseV2(this.getSessionState(sessionId)),
+      ..._meta ? { _meta } : {}
     };
   }
   async listSessions(params) {
@@ -53252,6 +53565,8 @@ You have been logged out. Please try again.`);
     } finally {
       if (this.getSessionGeneration(params.sessionId) === closeGeneration) {
         this.sessions.delete(params.sessionId);
+        this.asyncQuestions.get(params.sessionId)?.dispose();
+        this.asyncQuestions.delete(params.sessionId);
         if (!this.v2PromptsInFlight.has(params.sessionId)) {
           AcpV2Connection.of(this.connection)?.forgetSession(params.sessionId);
         }
@@ -54028,7 +54343,7 @@ You have been logged out. Please try again.`);
     });
     const sessionState = this.getSessionState(params.sessionId);
     this.assertSteerInputSupported(params, sessionState);
-    const clientUserMessageId = randomUUID6();
+    const clientUserMessageId = randomUUID7();
     const turnId = await this.getSteerableTurnId(sessionState);
     if (turnId) {
       const injected = await this.injectSteerIntoActiveTurn(params, turnId, sessionState, clientUserMessageId);
@@ -55059,8 +55374,11 @@ You have been logged out. Please try again.`);
   }
   userInputToContentBlocks(input2) {
     switch (input2.type) {
-      case "text":
+      case "text": {
+        const asyncQuestionReply = renderAsyncQuestionReply(input2.text);
+        if (asyncQuestionReply !== null) return [{ type: "text", text: asyncQuestionReply }];
         return desktopAttachmentHistory(input2.text) ?? (input2.text.length > 0 ? [{ type: "text", text: input2.text }] : []);
+      }
       case "image":
         return [{
           type: "text",
@@ -55439,7 +55757,7 @@ You have been logged out. Please try again.`);
       }
     }
     const promptKind = this.availableCommands.classifyPrompt(request.prompt);
-    const messageId = randomUUID6();
+    const messageId = randomUUID7();
     const session = new ACPSessionConnection(this.connection, sessionId);
     let failure3 = null;
     this.v2PromptsInFlight.add(sessionId);
@@ -55763,11 +56081,13 @@ You have been logged out. Please try again.`);
           await observeInteraction(event);
           if (!promptNotificationsActive) {
             await promptEventHandler.handleSessionScopedNotification(event);
+            this.asyncQuestionsFor(sessionState).handleNotification(event);
             await this.trackCodexTurnCompletion(sessionState, event, promptEventHandler);
             return;
           }
           const completesActiveTurn = event.method === "turn/completed" && event.params.threadId === sessionState.sessionId && event.params.turn.id === sessionState.currentTurnId;
           await promptEventHandler.handleNotification(event);
+          this.asyncQuestionsFor(sessionState).handleNotification(event);
           if (completesActiveTurn) {
             promptNotificationsActive = false;
           }
@@ -56000,7 +56320,7 @@ You have been logged out. Please try again.`);
           activePrompt.currentTurn = null;
           sessionState.currentTurnId = null;
           sessionState.interruptTurnId = null;
-          const implementationClientUserMessageId = insertion !== void 0 ? randomUUID6() : void 0;
+          const implementationClientUserMessageId = insertion !== void 0 ? randomUUID7() : void 0;
           if (implementationClientUserMessageId !== void 0) {
             registerSyntheticInsertion(implementationClientUserMessageId, implementationRequest.prompt);
           }
@@ -56211,12 +56531,28 @@ You have been logged out. Please try again.`);
     if (this.recovery === null || !lost.aborted || !sessionState.subagents.hasOutstanding()) return;
     throw this.recovery.errorForGeneration(generation);
   }
+  /** The async questions of a session, created on first use. */
+  asyncQuestionsFor(sessionState) {
+    const sessionId = sessionState.sessionId;
+    let questions = this.asyncQuestions.get(sessionId);
+    if (questions === void 0) {
+      questions = new AsyncQuestionElicitations(sessionId, this.clientCapabilities, new AsyncQuestionClient(
+        sessionId,
+        this.connection,
+        this.clientCapabilities,
+        () => this.codexAcpClient
+      ));
+      this.asyncQuestions.set(sessionId, questions);
+    }
+    return questions;
+  }
   /**
    * Ends what a prompt showed as running when its app-server died: open tool calls of the session and of its native
    * subagent sessions, the subagent sessions themselves and compactions. Nothing will ever complete them.
    */
   async finishPromptAfterAppServerLoss(sessionState, eventHandler, promptClient, elicitations, state) {
     try {
+      this.asyncQuestions.get(sessionState.sessionId)?.dispose();
       await elicitations?.completeAllUrlElicitations();
       const sessionIds = /* @__PURE__ */ new Set([sessionState.sessionId, ...sessionState.subagents.childSessionIds()]);
       await this.failUnfinishedToolCalls(sessionIds);

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "2.5.0-alas.1",
+  "version": "2.5.0-alas.3",
   "description": "",
   "main": "dist/index.js",
   "bin": {
@@ -81,6 +81,6 @@
   "alasDownstream": {
     "upstreamVersion": "2.5.0",
     "upstreamCommit": "34e08970aa324a2be985f5080674d5aa91d7666f",
-    "sourceCommit": "845c14e611fff5b534ecd38847d0b3dc1b69d0e6"
+    "sourceCommit": "de8d4c961871fc0584ca1bd89f31a8de95066c65"
   }
 }