diffprism 1.4.0 → 1.5.0

package/README.md

@@ -79,7 +79,7 @@ Reviews are **one per repo**: opening a review for a repo that already has one u
 |------|---------|
 | `annotate` | Post findings inline on the diff; `warning` flags the session for attention |
 | `get_review_comments` | Read every thread on the session; `awaiting_reply` narrows to unanswered ones |
-| `reply` | Reply to a thread — answer the reviewer's question on a line |
+| `reply` | Reply to a thread, then keep listening for what the reviewer does next |
 | `wait_for_comments` | Block until the reviewer writes something the agent hasn't answered |
 | `get_review_state` | Session status, attention and new-changes flags, and annotations |
 | `get_user_focus` | What file/line the user is currently viewing in the browser |
@@ -89,7 +89,7 @@ Reviews are **one per repo**: opening a review for a repo that already has one u
 
 In a local review, **Ask agent now** in a line's comment form asks the agent while you're still reviewing: the agent's wait for your decision ends with your question, it answers in the thread, and goes back to waiting.
 
-PR reviews are opened with `diffprism review <PR URL>` or the dashboard — not by `open_review` — and your AI then works inside them with the tools above. Click a line to ask the agent about it; an agent listening with `wait_for_comments` answers in the thread. Nothing starts an agent for you: if none has picked a question up, the thread says so and names the session to ask Claude Code about.
+PR reviews are opened with `diffprism review <PR URL>` or the dashboard — not by `open_review` — and your AI then works inside them with the tools above. Click a line to ask the agent about it; an agent listening with `wait_for_comments` answers in the thread, and stays listening for your next question until you tell it to stop. Nothing starts an agent for you: if none has picked a question up, the thread says so and names the session to ask Claude Code about. That one prompt is enough — the agent is handed the checkout, branch, PR and the code you asked about along with the question.
 
 When you're done, **Approve**, **Request changes** or **Comment** from the bar at the bottom: DiffPrism posts it to GitHub as a pull request review. Your threads are a conversation with the agent, so none of them goes to GitHub unless you tick it; a ticked thread posts your opening message as an inline review comment. The token comes from `GITHUB_TOKEN`, `gh auth token`, or `~/.diffprism/config.json`.
 
@@ -113,7 +113,7 @@ DiffPrism also works for reviewing local agent-generated changes:
 ```bash
 diffprism review                    # Review all changes (staged + unstaged)
 diffprism review --staged           # Staged changes only
-diffprism review HEAD~3             # Last 3 commits
+diffprism review HEAD~3..HEAD       # Last 3 commits
 diffprism review main..feature      # Branch diff
 ```
 
@@ -181,6 +181,7 @@ skill tells them so.
 ## CLI Reference
 
 ```bash
+diffprism demo                      # Open a sample review
 diffprism review <ref>              # Open a review (PR URL, git ref, or flags)
 diffprism setup                     # Configure Claude Code integration
 diffprism setup --global            # Global setup (no git repo needed)
@@ -189,10 +190,12 @@ diffprism server status             # Check server status
 diffprism server stop               # Stop the server
 diffprism hook install              # Gate commits on a review
 diffprism hook uninstall            # Remove the gate
+diffprism hook pre-commit           # Run the gate (what the installed hook calls)
 diffprism reply --session <id> <annotation-id> "…"  # Answer a reviewer's question, as the agent
 diffprism feedback                  # Share feedback as a prefilled GitHub issue
 diffprism feedback --bug            # Report a bug, including the last error
 diffprism teardown                  # Remove configuration
+diffprism serve                     # Run the MCP server over stdio (your MCP client launches this)
 ```
 
 ## Feedback
@@ -215,6 +218,7 @@ cd diffprism
 pnpm install
 pnpm test
 pnpm run build
+pnpm docs:check                     # Fail if docs disagree with the code (runs in CI)
 pnpm cli review --staged            # Run CLI from source
 ```
 

package/dist/bin.js

@@ -5,7 +5,7 @@ import {
 } from "./chunk-RFDSC6MC.js";
 import {
   demo
-} from "./chunk-6P6QJPWT.js";
+} from "./chunk-4JLGL3O6.js";
 import {
   COMMIT_GATE_DIFF_REF,
   DEFAULT_DIFF_REF,
@@ -26,14 +26,14 @@ import {
   recordError,
   startGlobalServer,
   submitReviewToServer
-} from "./chunk-SCQFIDIK.js";
+} from "./chunk-M5NJBIOV.js";
 import {
   getDiff
 } from "./chunk-GGK6TIQZ.js";
 import "./chunk-DHCVZGHE.js";
 import "./chunk-JSBRDJBE.js";
 
-// cli/src/index.ts
+// cli/src/program.ts
 import { Command } from "commander";
 
 // cli/src/commands/hook.ts
@@ -477,7 +477,7 @@ This should happen automatically after significant changes. You don't need the u
    - **\`dismissed\`** \u2014 the reviewer closed it without deciding. Ask before continuing.
    - If \`postReviewAction\` is \`"commit"\` \u2014 commit the changes. If \`"commit_and_pr"\` \u2014 commit and open a PR.
 4. If it returns \`status: "timed_out"\`, the reviewer is still reading. Keep waiting with \`mcp__diffprism__get_review_result\` (\`wait: true\`).
-5. If it returns \`status: "reviewer_asked"\`, the reviewer asked you something before deciding. Answer each thread with \`mcp__diffprism__reply\` (its \`id\` is the \`annotation_id\`) \u2014 and change the code if that's what they asked for. Then wait again with \`mcp__diffprism__get_review_result\` (\`wait: true\`), which can return \`reviewer_asked\` again.
+5. If it returns \`status: "reviewer_asked"\`, the reviewer asked you something before deciding. Answer each thread with \`mcp__diffprism__reply\` (its \`id\` is the \`annotation_id\`) \u2014 and change the code if that's what they asked for. \`reply\` goes back to waiting by itself and returns what happened next as \`next\`: another question (\`reviewer_asked\`) to answer the same way, the decision (\`decided\`), or \`timed_out\` \u2014 then wait with \`mcp__diffprism__get_review_result\` (\`wait: true\`).
 
 **While a review is open, wait for it.** Don't ask the user whether they've finished, and don't move on to other work \u2014 their decision is the answer, and it arrives through the tool. Asking in the terminal splits the conversation in two and the decision gets lost between them.
 
@@ -514,11 +514,11 @@ Pull requests are opened by the user \u2014 \`diffprism review <PR URL>\` or "Re
 
 The reviewer can also ask you questions on lines of the PR. Hold that conversation in the dashboard, not the terminal:
 
-1. \`mcp__diffprism__wait_for_comments\` \u2014 blocks until the reviewer writes something you haven't answered, then returns those threads.
-2. \`mcp__diffprism__reply\` \u2014 answer each thread, passing its \`annotation_id\`.
-3. Wait again. On \`timed_out\`, nothing new was said \u2014 keep waiting until the user tells you to stop.
+1. \`mcp__diffprism__wait_for_comments\` \u2014 blocks until the reviewer writes something you haven't answered, then returns those threads. Each carries \`hunk\`, the code it's on, and the response carries \`review\`: the checkout on disk (\`projectPath\`), the branch, and the PR. That's enough to start answering \u2014 you don't need to look the review up first. If \`localRepoConnected\` is false there's no clone here; answer from the hunk and the PR.
+2. \`mcp__diffprism__reply\` \u2014 answer a thread, passing its \`annotation_id\`. It goes back to listening by itself and returns what happened next as \`next\`: more questions to answer the same way, or \`timed_out\` \u2014 then call \`wait_for_comments\` again.
+3. Keep going until the user tells you to stop. Answering is not the end of the conversation; the reviewer's next question only reaches you if you're still listening.
 
-When no agent has read a question, the dashboard tells the reviewer so, and to ask you to answer their DiffPrism comments on a session id. When they do, run this loop with that \`session_id\`.
+When no agent has read a question, the dashboard tells the reviewer so, and to ask you to answer their DiffPrism comments on a session id. When they do, call \`wait_for_comments\` with that \`session_id\` \u2014 it returns at once with what's waiting \u2014 and run this loop.
 
 A PR review and a working-copy review can be open for the same clone at once. If a tool reports more than one session, pass the \`session_id\` of the one you mean.
 
@@ -542,8 +542,8 @@ A PR review and a working-copy review can be open for the same clone at once. If
 |------|---------|
 | \`annotate\` | Post one or more findings. \`warning\` flags the session for attention. |
 | \`get_review_comments\` | Every thread on the review; \`awaiting_reply\` narrows to threads waiting for an answer. |
-| \`reply\` | Reply to a thread \u2014 answer the reviewer's question or follow up on a finding. |
-| \`wait_for_comments\` | Block until the reviewer writes something you haven't answered. |
+| \`reply\` | Reply to a thread, then keep listening and return what happens next. |
+| \`wait_for_comments\` | Block until the reviewer writes something you haven't answered; returns it with the code and where the review is. |
 | \`get_review_state\` | Session status, attention and new-changes flags, and annotations. |
 | \`get_user_focus\` | What the user is currently looking at. |
 | \`get_pr_context\` | PR overview: metadata, briefing, file list, local clone status. |
@@ -721,7 +721,7 @@ async function setupInteractive(flags) {
 }
 async function runDemo(dev) {
   console.log("");
-  const { demo: demo2 } = await import("./demo-GHOE7YNU.js");
+  const { demo: demo2 } = await import("./demo-5UQ7CLKT.js");
   await demo2({ dev });
 }
 async function setupBatch(flags) {
@@ -1218,33 +1218,38 @@ ${url}`
   }
 }
 
+// cli/src/program.ts
+function createProgram() {
+  const program = new Command();
+  program.name("diffprism").description("Local-first code review tool for agent-generated changes").version(describeVersion(currentVersion()));
+  program.action(defaultAction);
+  program.command("demo").description("Open a sample review to see DiffPrism in action").option("--dev", "Use Vite dev server").action(demo);
+  program.command("review [ref]").description("Open a browser-based diff review (local git ref or GitHub PR ref like owner/repo#123)").option("--staged", "Review staged changes").option("--unstaged", "Review unstaged changes").option("-t, --title <title>", "Review title").option("--reasoning <text>", "Agent reasoning about the changes").option("--dev", "Use Vite dev server with HMR instead of static files").option("--post-to-github", "Automatically post review back to GitHub without prompting").action(review);
+  program.command("review-pr <pr>", { hidden: true }).action((pr, flags) => review(pr, flags));
+  const hookCmd = program.command("hook").description("Git hook integration \u2014 gate commits on a human review");
+  hookCmd.command("pre-commit").description("Run the review gate for the staged changes (called from a git hook)").option("--min-lines <n>", "Staged lines required to trigger a review (default: 120)").option("--dev", "Use Vite dev server").action((flags) => {
+    void preCommitHook(flags);
+  });
+  hookCmd.command("install").description("Add the diffprism gate to this repo's pre-commit hook").action(() => {
+    installHook();
+  });
+  hookCmd.command("uninstall").description("Remove the diffprism gate from this repo's pre-commit hook").action(() => {
+    uninstallHook();
+  });
+  program.command("feedback").description("Open a prefilled GitHub issue to share feedback or report a bug \u2014 you review it before anything is sent").option("--bug", "Report a bug, including the last error DiffPrism hit").option("-m, --message <text>", "Start the issue with this text").option("--print", "Print the issue URL instead of opening a browser").action((flags) => feedback(flags));
+  program.command("reply <annotation-id> <message...>").description("Answer a reviewer's question on an open review, as the agent").requiredOption("--session <id>", "The review the question is on").option("--agent <name>", "Name shown on the reply", "agent").action((annotationId, message2, flags) => reply(annotationId, message2, flags));
+  program.command("serve").description("Start the MCP server for Claude Code integration").action(serve);
+  program.command("setup").description("Configure DiffPrism for Claude Code integration").option("--global", "Configure globally (skill + permissions, no git repo required)").option("--force", "Overwrite existing configuration files").option("--dev", "Use Vite dev server").option("--no-demo", "Skip the demo review after setup").action((flags) => {
+    setup(flags);
+  });
+  program.command("teardown").description("Remove DiffPrism configuration from the current project").option("--global", "Remove global configuration (skill + permissions at ~/.claude/)").option("-q, --quiet", "Suppress output").action((flags) => {
+    teardown(flags);
+  });
+  const serverCmd = program.command("server").description("Start the global DiffPrism server for multi-session reviews").option("-p, --port <port>", "HTTP API port (default: 24680)").option("--ws-port <port>", "WebSocket port (default: 24681)").option("--dev", "Use Vite dev server with HMR instead of static files").option("--background", "Start server as a background daemon").option("--_daemon", "Internal: run as spawned daemon (do not use directly)").action(server);
+  serverCmd.command("status").description("Check if the global server is running and list active sessions").action(serverStatus);
+  serverCmd.command("stop").description("Stop the running global server").action(serverStop);
+  return program;
+}
+
 // cli/src/index.ts
-var program = new Command();
-program.name("diffprism").description("Local-first code review tool for agent-generated changes").version(describeVersion(currentVersion()));
-program.action(defaultAction);
-program.command("demo").description("Open a sample review to see DiffPrism in action").option("--dev", "Use Vite dev server").action(demo);
-program.command("review [ref]").description("Open a browser-based diff review (local git ref or GitHub PR ref like owner/repo#123)").option("--staged", "Review staged changes").option("--unstaged", "Review unstaged changes").option("-t, --title <title>", "Review title").option("--reasoning <text>", "Agent reasoning about the changes").option("--dev", "Use Vite dev server with HMR instead of static files").option("--post-to-github", "Automatically post review back to GitHub without prompting").action(review);
-program.command("review-pr <pr>", { hidden: true }).action((pr, flags) => review(pr, flags));
-var hookCmd = program.command("hook").description("Git hook integration \u2014 gate commits on a human review");
-hookCmd.command("pre-commit").description("Run the review gate for the staged changes (called from a git hook)").option("--min-lines <n>", "Staged lines required to trigger a review (default: 120)").option("--dev", "Use Vite dev server").action((flags) => {
-  void preCommitHook(flags);
-});
-hookCmd.command("install").description("Add the diffprism gate to this repo's pre-commit hook").action(() => {
-  installHook();
-});
-hookCmd.command("uninstall").description("Remove the diffprism gate from this repo's pre-commit hook").action(() => {
-  uninstallHook();
-});
-program.command("feedback").description("Open a prefilled GitHub issue to share feedback or report a bug \u2014 you review it before anything is sent").option("--bug", "Report a bug, including the last error DiffPrism hit").option("-m, --message <text>", "Start the issue with this text").option("--print", "Print the issue URL instead of opening a browser").action((flags) => feedback(flags));
-program.command("reply <annotation-id> <message...>").description("Answer a reviewer's question on an open review, as the agent").requiredOption("--session <id>", "The review the question is on").option("--agent <name>", "Name shown on the reply", "agent").action((annotationId, message2, flags) => reply(annotationId, message2, flags));
-program.command("serve").description("Start the MCP server for Claude Code integration").action(serve);
-program.command("setup").description("Configure DiffPrism for Claude Code integration").option("--global", "Configure globally (skill + permissions, no git repo required)").option("--force", "Overwrite existing configuration files").option("--dev", "Use Vite dev server").option("--no-demo", "Skip the demo review after setup").action((flags) => {
-  setup(flags);
-});
-program.command("teardown").description("Remove DiffPrism configuration from the current project").option("--global", "Remove global configuration (skill + permissions at ~/.claude/)").option("-q, --quiet", "Suppress output").action((flags) => {
-  teardown(flags);
-});
-var serverCmd = program.command("server").description("Start the global DiffPrism server for multi-session reviews").option("-p, --port <port>", "HTTP API port (default: 24680)").option("--ws-port <port>", "WebSocket port (default: 24681)").option("--dev", "Use Vite dev server with HMR instead of static files").option("--background", "Start server as a background daemon").option("--_daemon", "Internal: run as spawned daemon (do not use directly)").action(server);
-serverCmd.command("status").description("Check if the global server is running and list active sessions").action(serverStatus);
-serverCmd.command("stop").description("Stop the running global server").action(serverStop);
-program.parse();
+createProgram().parse();

package/dist/{chunk-6P6QJPWT.js → chunk-4JLGL3O6.js}

@@ -1,7 +1,7 @@
 import {
   ensureServer,
   submitReviewToServer
-} from "./chunk-SCQFIDIK.js";
+} from "./chunk-M5NJBIOV.js";
 import {
   parseDiff
 } from "./chunk-GGK6TIQZ.js";

package/dist/{chunk-SCQFIDIK.js → chunk-M5NJBIOV.js}

@@ -96,12 +96,22 @@ function pickedUpByAgent(annotation, agentReadAt) {
   return agentReadAt !== void 0 && agentReadAt > lastMessageAt(annotation);
 }
 
+// packages/core/src/diff-scope.ts
+var DEFAULT_DIFF_REF = "working-copy";
+var COMMIT_GATE_DIFF_REF = "staged";
+var DIFF_REF_DESCRIPTION = 'Which changes to review. "working-copy" (the default): everything not yet committed, staged and unstaged shown as separate groups. "staged": only what the next commit would contain. "unstaged": only edits not yet staged. Or a ref range such as "HEAD~3..HEAD" or "main..feature".';
+
+// packages/core/src/feedback.ts
+import fs3 from "fs";
+import os2 from "os";
+import path3 from "path";
+
 // packages/core/src/build-info.ts
 import fs2 from "fs";
 import path2 from "path";
 import { fileURLToPath } from "url";
 function builtAt() {
-  return true ? 1789619773143 : null;
+  return true ? 1789699543800 : null;
 }
 function getBuildInfo() {
   let dir = path2.dirname(fileURLToPath(import.meta.url));
@@ -127,19 +137,11 @@ function describeVersion(version) {
   return info.dev ? `${version} (dev build \u2014 ${info.root})` : version;
 }
 
-// packages/core/src/diff-scope.ts
-var DEFAULT_DIFF_REF = "working-copy";
-var COMMIT_GATE_DIFF_REF = "staged";
-var DIFF_REF_DESCRIPTION = 'Which changes to review. "working-copy" (the default): everything not yet committed, staged and unstaged shown as separate groups. "staged": only what the next commit would contain. "unstaged": only edits not yet staged. Or a ref range such as "HEAD~3..HEAD" or "main..feature".';
-
 // packages/core/src/feedback.ts
-import fs3 from "fs";
-import os2 from "os";
-import path3 from "path";
 var ISSUES_NEW_URL = "https://github.com/CodeJonesW/diffprism/issues/new";
 var MAX_ERROR_CHARS = 1500;
 function currentVersion() {
-  return true ? "1.4.0" : "0.0.0-dev";
+  return true ? "1.5.0" : "0.0.0-dev";
 }
 function describeEnvironment() {
   return {

package/dist/{demo-GHOE7YNU.js → demo-5UQ7CLKT.js}

@@ -1,7 +1,7 @@
 import {
   demo
-} from "./chunk-6P6QJPWT.js";
-import "./chunk-SCQFIDIK.js";
+} from "./chunk-4JLGL3O6.js";
+import "./chunk-M5NJBIOV.js";
 import "./chunk-GGK6TIQZ.js";
 import "./chunk-DHCVZGHE.js";
 import "./chunk-JSBRDJBE.js";

package/dist/mcp-server.js

@@ -14,7 +14,7 @@ import {
   recordError,
   submitReviewToServer,
   waitForDecision
-} from "./chunk-SCQFIDIK.js";
+} from "./chunk-M5NJBIOV.js";
 import {
   getDiff
 } from "./chunk-GGK6TIQZ.js";
@@ -81,11 +81,56 @@ async function readThreads(serverInfo, sessionId) {
   const { annotations } = await response.json();
   return annotations.map((a) => ({ ...a, awaitingReply: awaitingAgent(a) }));
 }
-function reviewerAskedResult(err, waitWith) {
+async function readReview(serverInfo, sessionId) {
+  let response;
+  try {
+    response = await fetch(
+      `http://localhost:${serverInfo.httpPort}/api/reviews/${sessionId}/payload`
+    );
+  } catch {
+    return null;
+  }
+  if (!response.ok) {
+    return null;
+  }
+  const { payload, projectPath } = await response.json();
+  return {
+    review: {
+      sessionId,
+      projectPath,
+      localRepoConnected: !projectPath.startsWith("github:"),
+      branch: payload.metadata.currentBranch,
+      pr: payload.metadata.githubPr ?? null,
+      title: payload.metadata.title
+    },
+    diffSet: payload.diffSet
+  };
+}
+function hunkFor(diffSet, annotation) {
+  const file = diffSet.files.find((f) => f.path === annotation.file);
+  if (!file) {
+    return null;
+  }
+  return file.hunks.find(
+    (hunk) => annotation.side === "old" ? annotation.line >= hunk.oldStart && annotation.line < hunk.oldStart + hunk.oldLines : annotation.line >= hunk.newStart && annotation.line < hunk.newStart + hunk.newLines
+  ) ?? null;
+}
+function answerableThreads(context, threads) {
+  return {
+    sessionId: context.review.sessionId,
+    review: context.review,
+    threads: threads.map((thread) => ({
+      ...thread,
+      awaitingReply: true,
+      hunk: hunkFor(context.diffSet, thread)
+    }))
+  };
+}
+async function reviewerAskedResult(serverInfo, err, waitWith) {
+  const context = await readReview(serverInfo, err.sessionId);
   return jsonResult({
     status: "reviewer_asked",
-    sessionId: err.sessionId,
-    threads: err.threads.map((t) => ({ ...t, awaitingReply: true })),
+    ...context ? answerableThreads(context, err.threads) : { sessionId: err.sessionId, threads: err.threads.map((t) => ({ ...t, awaitingReply: true })) },
     message: `The reviewer asked you something before deciding. Answer each thread with reply (session_id: ${err.sessionId}, annotation_id from threads) \u2014 change the code too if that's what they asked for. Then ${waitWith}. The review stays open; the decision still comes.`
   });
 }
@@ -124,7 +169,7 @@ var annotationSchema = z.object({
     "other"
   ]).optional().describe("Category of the finding (defaults to 'other')")
 });
-async function startMcpServer() {
+function createMcpServer() {
   const server = new McpServer({
     name: "diffprism",
     version: currentVersion()
@@ -176,7 +221,7 @@ async function startMcpServer() {
           });
         } catch (err) {
           if (err instanceof ReviewerAskedError) {
-            return reviewerAskedResult(err, `wait for the decision with get_review_result (session_id: ${err.sessionId}, wait: true)`);
+            return await reviewerAskedResult(serverInfo, err, `wait for the decision with get_review_result (session_id: ${err.sessionId}, wait: true)`);
           }
           if (err instanceof ReviewTimeoutError) {
             return jsonResult({
@@ -217,7 +262,7 @@ ${REPORT_HINT}`);
         return jsonResult(await waitForDecision(serverInfo, sessionId, Math.min(timeout ?? 300, 600) * 1e3));
       } catch (err) {
         if (err instanceof ReviewerAskedError) {
-          return reviewerAskedResult(err, "call get_review_result with wait: true again");
+          return await reviewerAskedResult(serverInfo, err, "call get_review_result with wait: true again");
         }
         if (err instanceof ReviewTimeoutError) {
           return jsonResult({
@@ -382,14 +427,17 @@ ${REPORT_HINT}`);
   );
   server.tool(
     "reply",
-    "Reply to a thread on an open review \u2014 answer the reviewer's question, or follow up on a finding. The reply appears under the thread in the dashboard straight away.",
+    "Reply to a thread on an open review \u2014 answer the reviewer's question, or follow up on a finding. The reply appears under the thread in the dashboard straight away, and then this goes back to listening and returns whatever happens next: the reviewer's next question, their decision, or `timed_out`. Stay in that loop until they tell you to stop.",
     {
       ...targetParams,
       annotation_id: z.string().describe("The thread to reply to (an annotation id from get_review_comments or wait_for_comments)"),
       body: z.string().describe("Your reply"),
-      source_agent: z.string().optional().describe("Who is replying, e.g. 'pr-reviewer'")
+      source_agent: z.string().optional().describe("Who is replying, e.g. 'pr-reviewer'"),
+      then_wait: z.boolean().optional().describe(
+        "Keep listening after replying (default true). With false, returns as soon as the reply is posted \u2014 use it when you have several threads to answer and want to post them all first."
+      )
     },
-    async ({ session_id, repo_path, annotation_id, body, source_agent }) => withSession({ session_id, repo_path }, async ({ serverInfo, sessionId }) => {
+    async ({ session_id, repo_path, annotation_id, body, source_agent, then_wait }) => withSession({ session_id, repo_path }, async ({ serverInfo, sessionId }) => {
       const response = await fetch(
         `http://localhost:${serverInfo.httpPort}/api/reviews/${sessionId}/annotations/${annotation_id}/replies`,
         {
@@ -402,7 +450,33 @@ ${REPORT_HINT}`);
       if (!response.ok) {
         return toolError(`Error: ${data.error ?? `server returned ${response.status}`}`);
       }
-      return jsonResult({ sessionId, annotationId: annotation_id, replyId: data.replyId });
+      const posted = { sessionId, annotationId: annotation_id, replyId: data.replyId };
+      if (then_wait === false) {
+        return jsonResult(posted);
+      }
+      try {
+        const result = await waitForDecision(serverInfo, sessionId, DEFAULT_WAIT_MS);
+        return jsonResult({ ...posted, next: { status: "decided", result } });
+      } catch (err) {
+        if (err instanceof ReviewerAskedError) {
+          const context = await readReview(serverInfo, sessionId);
+          return jsonResult({
+            ...posted,
+            next: context ? { status: "reviewer_asked", ...answerableThreads(context, err.threads) } : { status: "reviewer_asked", sessionId, threads: err.threads }
+          });
+        }
+        if (err instanceof ReviewTimeoutError) {
+          return jsonResult({
+            ...posted,
+            next: {
+              status: "timed_out",
+              sessionId,
+              message: "Your reply is posted and the reviewer hasn't said anything since. Keep listening: wait_for_comments in a PR review, or get_review_result with wait: true if you're waiting for their decision. Don't ask them in the terminal."
+            }
+          });
+        }
+        throw err;
+      }
     })
   );
   server.tool(
@@ -422,7 +496,10 @@ ${REPORT_HINT}`);
         }
         const waiting = threads.filter((t) => t.awaitingReply);
         if (waiting.length > 0) {
-          return jsonResult({ sessionId, threads: waiting });
+          const context = await readReview(serverInfo, sessionId);
+          return jsonResult(
+            context ? answerableThreads(context, waiting) : { sessionId, threads: waiting }
+          );
         }
         if (Date.now() - start >= maxWaitMs) {
           return jsonResult({
@@ -568,11 +645,16 @@ ${available.join("\n")}`);
       });
     })
   );
+  return server;
+}
+async function startMcpServer() {
+  const server = createMcpServer();
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }
 export {
   DEFAULT_WAIT_MS,
+  createMcpServer,
   resolveTarget,
   startMcpServer
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "diffprism",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "type": "module",
   "description": "Local-first code review tool for agent-generated code changes",
   "bin": {
@@ -16,6 +16,7 @@
     "dev": "pnpm -r run dev",
     "lint": "pnpm -r run lint",
     "test": "pnpm -r run test",
+    "docs:check": "pnpm -F diffprism-cli docs:check",
     "cli": "pnpm -F @diffprism/ui build && tsx cli/src/index.ts",
     "prepublishOnly": "pnpm run build"
   },