@tryarcanist/cli 0.1.172 → 0.1.174

package/README.md

@@ -226,6 +226,19 @@ Repeatable `--uploaded-file <path>` flags attach local UTF-8 text files to the f
 JSON mode returns `{sessionId, promptId?}`.
 With `--wait`, JSON mode also includes best-effort result fields when available: `prUrl?`, `publishedBranch?`, `lastBranch?`.
 
+### `arcanist sessions respond <session-id> [answer]`
+
+Answers a pending `question` event from `sessions events --follow`.
+Pass the `questionId` from the question event so the answer is durable and safe across reconnects.
+
+```bash
+arcanist sessions respond abc123 "Use PostgreSQL" --question-id q_123
+printf "Use PostgreSQL" | arcanist sessions respond abc123 --question-id q_123 --answer-stdin --json
+```
+
+JSON mode returns the raw respond payload plus `sessionId`.
+If the session is no longer waiting for input, the command exits with conflict and points back to `sessions events --follow --json`.
+
 ### `arcanist sessions stop <session-id>`
 
 Stops the active run for a session. Idempotent: if no sandbox is active, the server returns `already_stopped`.

package/dist/index.js

@@ -506,6 +506,15 @@ function randomIdempotencyKey() {
 function assertArcanistSessionMutationAllowed(subcommand) {
   const role = process.env.ARCANIST_AGENT_ROLE?.trim();
   if (role !== "verification") return;
+  if (subcommand === "respond") {
+    throw new CliError(
+      "user",
+      "`arcanist sessions respond` is disabled inside verification sessions because verification agents cannot mutate the session under review.",
+      {
+        hint: "Report the unanswered question as a verification blocker instead."
+      }
+    );
+  }
   throw new CliError(
     "user",
     `\`arcanist sessions ${subcommand}\` is disabled inside ${role} sessions because nested Arcanist sessions are not observable to the verifier.`,
@@ -3502,6 +3511,57 @@ async function qaCommand(prUrl, options, command) {
   console.log(`Follow with: arcanist sessions events ${sessionId} --follow --json`);
 }
 
+// src/commands/respond.ts
+async function resolveAnswerInput(answerArg, options) {
+  const shouldReadStdin = options.answerStdin === true || answerArg === "-";
+  const answer = shouldReadStdin ? await readStdin() : answerArg;
+  if (!answer || answer.trim().length === 0) {
+    throw new CliError(
+      "user",
+      "Missing answer. Pass an answer argument, use '-' to read stdin, or pass --answer-stdin."
+    );
+  }
+  return answer;
+}
+async function respondCommand(sessionId, answerArg, options = {}, command) {
+  assertArcanistSessionMutationAllowed("respond");
+  const questionId = options.questionId?.trim();
+  if (!questionId) {
+    throw new CliError("user", "Missing --question-id for the pending question.", {
+      hint: `Find the question id with: arcanist sessions events ${sessionId} --follow --json`
+    });
+  }
+  const { config } = resolveBusinessContext(command, options);
+  const answer = await resolveAnswerInput(answerArg, options);
+  try {
+    const payload = await apiFetch(config, `/api/sessions/${sessionId}/respond`, {
+      method: "POST",
+      body: JSON.stringify({ answer, questionId })
+    });
+    emit(command, options, { sessionId, ...payload }, () => console.log(`Answer sent to session ${sessionId}.`));
+  } catch (err) {
+    const conflict = parseRespondConflict(err);
+    if (!conflict) throw err;
+    throw new CliError("conflict", conflict.message, {
+      data: { reason: conflict.reason },
+      hint: `Inspect pending questions with: arcanist sessions events ${sessionId} --follow --json`
+    });
+  }
+}
+function parseRespondConflict(err) {
+  if (!(err instanceof ApiError) || err.status !== 409) return null;
+  try {
+    const body = JSON.parse(err.body);
+    if (body.error !== "session_not_respondable") return null;
+    return {
+      message: body.reason ? `Session cannot be answered from phase=${body.reason}.` : "Session does not have a pending question.",
+      reason: body.reason ?? "session_not_respondable"
+    };
+  } catch {
+    return null;
+  }
+}
+
 // src/commands/sandbox.ts
 import { execFileSync } from "child_process";
 import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
@@ -5009,6 +5069,17 @@ addSendOptions(sessions.command("send").description("Send a message to an existi
 addQaOptions(sessions.command("qa").description("Start a QA verification session for a GitHub pull request")).action(
   (prUrl, options, command) => qaCommand(prUrl, options, command)
 );
+sessions.command("respond").description("Answer a pending session question").argument("<session-id>", "Session ID").argument("[answer]", "Answer text, or '-' to read stdin").option("--answer-stdin", "Read answer from stdin").requiredOption("--question-id <id>", "Question ID from the question event").addHelpText(
+  "after",
+  `
+Examples:
+  arcanist sessions respond <session-id> "Use PostgreSQL" --question-id q_123
+  printf "Use PostgreSQL" | arcanist sessions respond <session-id> --question-id q_123 --answer-stdin --json
+
+JSON:
+JSON mode returns the raw respond payload plus sessionId.
+`
+).action((sessionId, answer, options, command) => respondCommand(sessionId, answer, options, command));
 sessions.command("stop").description("Stop the active run for a session").argument("<session-id>", "Session ID").addHelpText(
   "after",
   `

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryarcanist/cli",
-  "version": "0.1.172",
+  "version": "0.1.174",
   "description": "CLI for Arcanist — create and manage coding agent sessions",
   "type": "module",
   "bin": {