diffprism 0.48.2 → 1.0.0

package/dist/mcp-server.js

@@ -1,15 +1,23 @@
 import {
-  isPrRef,
-  parsePrRef
-} from "./chunk-24B33UN6.js";
+  isPrRef
+} from "./chunk-EPU4F7WT.js";
 import {
+  DEFAULT_DIFF_REF,
+  DIFF_REF_DESCRIPTION,
+  REPORT_HINT,
+  ReviewTimeoutError,
+  ReviewerAskedError,
+  awaitingAgent,
+  currentVersion,
   ensureServer,
   isServerAlive,
-  submitReviewToServer
-} from "./chunk-EPUCA2N5.js";
+  recordError,
+  submitReviewToServer,
+  waitForDecision
+} from "./chunk-CU2BAL6Q.js";
 import {
   getDiff
-} from "./chunk-QGWYCEJN.js";
+} from "./chunk-3GMPE2ZR.js";
 import {
   analyze
 } from "./chunk-DHCVZGHE.js";
@@ -19,385 +27,249 @@ import "./chunk-JSBRDJBE.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-var lastGlobalSessionId = null;
-var lastGlobalServerInfo = null;
-async function resolveSessionId(explicitId, serverInfo) {
-  if (explicitId) return explicitId;
-  if (lastGlobalSessionId) return lastGlobalSessionId;
-  try {
-    const response = await fetch(
-      `http://localhost:${serverInfo.httpPort}/api/reviews`
-    );
-    if (response.ok) {
-      const data = await response.json();
-      if (data.sessions.length > 0) {
-        const sorted = [...data.sessions].sort((a, b) => b.createdAt - a.createdAt);
-        return sorted[0].id;
-      }
-    }
-  } catch {
-  }
-  return null;
+var DEFAULT_WAIT_MS = 6e5;
+var NO_SERVER = "No DiffPrism server is running. A review has to be open before this tool can act on it \u2014 open one with open_review, `diffprism review`, or the DiffPrism dashboard.";
+function jsonResult(value) {
+  return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
 }
-async function handleLocalReview(diffRef, options) {
-  const serverInfo = await ensureServer({ silent: true });
-  const { result, sessionId } = await submitReviewToServer(
-    serverInfo,
-    diffRef,
-    {
-      title: options.title,
-      description: options.description,
-      reasoning: options.reasoning,
-      cwd: process.cwd(),
-      annotations: options.annotations,
-      diffRef,
-      timeoutMs: options.timeoutMs ?? 0
-    }
+function toolError(text) {
+  return { content: [{ type: "text", text }], isError: true };
+}
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+var targetParams = {
+  session_id: z.string().optional().describe("The review session to act on. Takes precedence over repo_path."),
+  repo_path: z.string().optional().describe(
+    "Any directory inside the repository whose review to act on. Defaults to the directory this agent is running in \u2014 pass it when working on a repo other than your own."
+  )
+};
+async function resolveTarget(serverInfo, params) {
+  if (params.session_id) {
+    return { sessionId: params.session_id };
+  }
+  const lookupPath = params.repo_path ?? process.cwd();
+  const response = await fetch(
+    `http://localhost:${serverInfo.httpPort}/api/reviews/resolve?path=${encodeURIComponent(lookupPath)}`
   );
-  if (result) {
+  if (!response.ok) {
+    return { error: `Could not look up a review for ${lookupPath}: server returned ${response.status}.` };
+  }
+  const { repoRoot, sessions } = await response.json();
+  if (sessions.length === 1) {
+    return { sessionId: sessions[0].id };
+  }
+  const from = params.repo_path ? "repo_path" : "the current directory";
+  if (sessions.length === 0) {
     return {
-      mcpResult: {
-        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
-      },
-      sessionId,
-      serverInfo
+      error: `No review is open for ${repoRoot} (resolved from ${from}). Open one with open_review, \`diffprism review\`, or the DiffPrism dashboard \u2014 or pass session_id.`
     };
   }
+  const candidates = sessions.map((s) => `  ${s.id}  ${s.title ?? "(untitled)"}  (${[s.diffRef, s.status].filter(Boolean).join(", ")})`).join("\n");
   return {
-    mcpResult: {
-      content: [{
-        type: "text",
-        text: JSON.stringify({
-          status: "session_created",
-          sessionId,
-          message: "Review session opened in DiffPrism dashboard. Use get_review_result to check for a decision."
-        }, null, 2)
-      }]
-    },
-    sessionId,
-    serverInfo
+    error: `${sessions.length} reviews are open for ${repoRoot}. Pass session_id to choose one:
+${candidates}`
   };
 }
-async function handlePrReview(pr, options) {
-  const { owner, repo, number } = parsePrRef(pr);
-  const serverInfo = await ensureServer({ silent: true });
+async function readThreads(serverInfo, sessionId) {
   const response = await fetch(
-    `http://localhost:${serverInfo.httpPort}/api/pr/open`,
-    {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ prUrl: pr })
-    }
+    `http://localhost:${serverInfo.httpPort}/api/reviews/${sessionId}/annotations`
   );
-  const data = await response.json();
-  if (!response.ok || !data.sessionId) {
-    return {
-      mcpResult: {
-        content: [{ type: "text", text: `Error: ${data.error ?? "Failed to open PR"}` }],
-        isError: true
-      },
-      sessionId: "",
-      serverInfo
-    };
+  if (!response.ok) {
+    return null;
   }
-  const sessionId = data.sessionId;
-  if (options.timeoutMs && options.timeoutMs > 0) {
-    const start = Date.now();
-    while (Date.now() - start < options.timeoutMs) {
-      const resultResponse = await fetch(
-        `http://localhost:${serverInfo.httpPort}/api/reviews/${sessionId}/result`
-      );
-      if (resultResponse.ok) {
-        const resultData = await resultResponse.json();
-        if (resultData.result) {
-          return {
-            mcpResult: {
-              content: [{ type: "text", text: JSON.stringify(resultData.result, null, 2) }]
-            },
-            sessionId,
-            serverInfo
-          };
-        }
-      }
-      await new Promise((resolve) => setTimeout(resolve, 2e3));
+  const { annotations } = await response.json();
+  return annotations.map((a) => ({ ...a, awaitingReply: awaitingAgent(a) }));
+}
+function reviewerAskedResult(err, waitWith) {
+  return jsonResult({
+    status: "reviewer_asked",
+    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.`
+  });
+}
+async function withSession(params, run) {
+  try {
+    const serverInfo = await isServerAlive();
+    if (!serverInfo) {
+      return toolError(NO_SERVER);
+    }
+    const target = await resolveTarget(serverInfo, params);
+    if ("error" in target) {
+      return toolError(target.error);
     }
+    return await run({ serverInfo, sessionId: target.sessionId });
+  } catch (err) {
+    recordError("serve (MCP)", err);
+    return toolError(`Error: ${errorMessage(err)}
+${REPORT_HINT}`);
   }
-  return {
-    mcpResult: {
-      content: [{
-        type: "text",
-        text: JSON.stringify({
-          status: "session_created",
-          sessionId,
-          pr: `${owner}/${repo}#${number}`,
-          fileCount: data.fileCount,
-          localRepoConnected: !!data.localRepoPath,
-          localRepoPath: data.localRepoPath,
-          message: "PR review session opened in DiffPrism. Use get_pr_context, get_file_diff, get_file_context to explore the changes. Use add_review_comment to post findings."
-        }, null, 2)
-      }]
-    },
-    sessionId,
-    serverInfo
-  };
 }
+var diffRefParam = z.string().optional().describe(DIFF_REF_DESCRIPTION);
+var annotationSchema = z.object({
+  file: z.string().describe("File path within the diff"),
+  line: z.number().optional().describe("Line number to attach to (defaults to 1, for a note about the file as a whole)"),
+  body: z.string().describe("The finding, suggestion, or question"),
+  type: z.enum(["finding", "suggestion", "question", "warning"]).describe("Use 'warning' for anything the reviewer must look at \u2014 warnings flag the session for attention"),
+  confidence: z.number().min(0).max(1).optional().describe("Confidence in the finding (0-1, defaults to 1)"),
+  category: z.enum([
+    "security",
+    "performance",
+    "convention",
+    "correctness",
+    "complexity",
+    "test-coverage",
+    "documentation",
+    "other"
+  ]).optional().describe("Category of the finding (defaults to 'other')")
+});
 async function startMcpServer() {
   const server = new McpServer({
     name: "diffprism",
-    version: true ? "0.48.2" : "0.0.0-dev"
+    version: currentVersion()
   });
   server.tool(
     "open_review",
-    "Open a review session in the DiffPrism dashboard for local git changes or a GitHub pull request. Returns immediately with the session ID after registering the session. Use `get_review_result` with `wait: true` when you need the reviewer's decision before proceeding.",
+    'Open a review of local git changes in the DiffPrism dashboard and wait for the reviewer\'s decision. Blocks until they approve, request changes, or dismiss, then returns their ReviewResult (decision, inline comments, summary). If the reviewer asks you something first, returns status "reviewer_asked" with the threads: answer them with reply, then wait with get_review_result. Reviews are one per repo: opening again for the same repo updates the review already open instead of starting another, and keeps its annotations. Pass wait: false to get the session id back immediately instead. Pull requests are not opened here \u2014 open them with `diffprism review <PR URL>` or the dashboard, then use the PR tools.',
     {
-      diff_ref: z.string().describe(
-        'Git diff reference: "staged", "unstaged", "working-copy" (staged+unstaged grouped), a ref range like "HEAD~3..HEAD", or a GitHub PR ref like "owner/repo#123" or a GitHub PR URL'
-      ),
+      diff_ref: diffRefParam,
       title: z.string().optional().describe("Title for the review"),
       description: z.string().optional().describe("Description of the changes"),
-      reasoning: z.string().optional().describe("Summarize what you were trying to accomplish in this session in plain English. This is displayed as the session subtitle in the DiffPrism dashboard and is the primary way users identify sessions at a glance. Always populate this."),
-      post_to_github: z.boolean().optional().describe("Post the review back to GitHub after submission (only for PR refs, default: false)"),
-      timeout_ms: z.number().optional().describe("How long to wait for a review decision (ms). Defaults to 0 (non-blocking, returns immediately after session creation). Set to a positive value to poll for a result up to that duration before returning."),
-      annotations: z.array(
-        z.object({
-          file: z.string().describe("File path within the diff to annotate"),
-          line: z.number().describe("Line number to annotate"),
-          body: z.string().describe("The annotation text"),
-          type: z.enum(["finding", "suggestion", "question", "warning"]).describe("Type of annotation"),
-          confidence: z.number().min(0).max(1).optional().describe("Confidence in the finding (0-1, defaults to 1)"),
-          category: z.enum([
-            "security",
-            "performance",
-            "convention",
-            "correctness",
-            "complexity",
-            "test-coverage",
-            "documentation",
-            "other"
-          ]).optional().describe("Category of the finding (defaults to 'other')"),
-          source_agent: z.string().optional().describe("Agent identifier (e.g., 'security-reviewer')")
-        })
-      ).optional().describe("Initial annotations to attach to the review")
+      reasoning: z.string().optional().describe(
+        "Summarize what you were trying to accomplish in plain English. Shown as the session subtitle in the dashboard \u2014 the main way a reviewer tells sessions apart. Always populate this."
+      ),
+      annotations: z.array(annotationSchema).optional().describe("Findings to attach to the review when it opens"),
+      wait: z.boolean().optional().describe(
+        "Wait for the reviewer's decision (default true). With false, returns the session id at once; check for a decision later with get_review_result."
+      ),
+      timeout_ms: z.number().optional().describe(
+        `How long to wait for a decision (default ${DEFAULT_WAIT_MS}ms). If it runs out the review stays open, and the session id comes back so you can check again with get_review_result.`
+      )
     },
-    async ({ diff_ref, title, description, reasoning, post_to_github, timeout_ms, annotations }) => {
+    async ({ diff_ref = DEFAULT_DIFF_REF, title, description, reasoning, annotations, wait, timeout_ms }) => {
+      if (isPrRef(diff_ref)) {
+        return toolError(
+          "open_review does not open pull requests. Open a PR review with `diffprism review <PR URL>` or the DiffPrism dashboard, then use get_pr_context, get_file_diff, get_file_context and annotate on that session."
+        );
+      }
       try {
-        let mcpResult;
-        let sessionId;
-        let serverInfo;
-        if (isPrRef(diff_ref)) {
-          ({ mcpResult, sessionId, serverInfo } = await handlePrReview(diff_ref, {
-            title,
-            reasoning,
-            post_to_github,
-            timeoutMs: timeout_ms
-          }));
-        } else {
-          ({ mcpResult, sessionId, serverInfo } = await handleLocalReview(diff_ref, {
+        const serverInfo = await ensureServer({ silent: true });
+        const shouldWait = wait ?? true;
+        try {
+          const { result, sessionId } = await submitReviewToServer(serverInfo, diff_ref, {
             title,
             description,
             reasoning,
-            annotations,
-            timeoutMs: timeout_ms
-          }));
-        }
-        if (sessionId) {
-          lastGlobalSessionId = sessionId;
-          lastGlobalServerInfo = serverInfo;
+            cwd: process.cwd(),
+            annotations: annotations?.map((a) => ({ ...a, line: a.line ?? 1 })),
+            diffRef: diff_ref,
+            timeoutMs: shouldWait ? timeout_ms ?? DEFAULT_WAIT_MS : 0
+          });
+          if (result) {
+            return jsonResult(result);
+          }
+          return jsonResult({
+            status: "open",
+            sessionId,
+            message: "Review is open in the DiffPrism dashboard. Check for a decision with get_review_result."
+          });
+        } catch (err) {
+          if (err instanceof ReviewerAskedError) {
+            return reviewerAskedResult(err, `wait for the decision with get_review_result (session_id: ${err.sessionId}, wait: true)`);
+          }
+          if (err instanceof ReviewTimeoutError) {
+            return jsonResult({
+              status: "timed_out",
+              sessionId: err.sessionId,
+              message: `No decision after ${Math.round(err.waitedMs / 1e3)}s. The reviewer may still be reading \u2014 the review is open in their browser. Wait with get_review_result (session_id: ${err.sessionId}, wait: true). Don't ask the user about it in the meantime: their decision is the answer. Calling open_review again with an unchanged diff is also safe \u2014 it returns a decision already given.`
+            });
+          }
+          throw err;
         }
-        return mcpResult;
       } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Error: ${message}`
-            }
-          ],
-          isError: true
-        };
+        recordError("serve (MCP) open_review", err);
+        return toolError(`Error: ${errorMessage(err)}
+${REPORT_HINT}`);
       }
     }
   );
   server.tool(
-    "update_review_context",
-    "Push reasoning/context to a running DiffPrism review session. Non-blocking \u2014 returns immediately. Updates the review UI with agent reasoning without opening a new review. Requires a prior `open_review` call in this session.",
+    "get_review_result",
+    'Check the decision on a review that is already open \u2014 after open_review with wait: false, or after open_review timed out. Returns the ReviewResult once the reviewer has decided. Set wait: true to block until they do; the wait also ends with status "reviewer_asked" if they ask you something \u2014 reply, then wait again.',
     {
-      reasoning: z.string().optional().describe("Agent reasoning about the current changes"),
-      title: z.string().optional().describe("Updated title for the review"),
-      description: z.string().optional().describe("Updated description of the changes")
+      ...targetParams,
+      wait: z.boolean().optional().describe("Block until a decision arrives (up to timeout)"),
+      timeout: z.number().optional().describe("Max wait in seconds when wait is true (default 300, max 600)")
     },
-    async ({ reasoning, title, description }) => {
-      try {
-        const payload = {};
-        if (reasoning !== void 0) payload.reasoning = reasoning;
-        if (title !== void 0) payload.title = title;
-        if (description !== void 0) payload.description = description;
-        const serverInfo = lastGlobalServerInfo ?? await isServerAlive();
-        if (!serverInfo || !lastGlobalSessionId) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: "No DiffPrism session is running. Use `open_review` to start a review."
-              }
-            ]
-          };
-        }
+    async ({ session_id, repo_path, wait, timeout }) => withSession({ session_id, repo_path }, async ({ serverInfo, sessionId }) => {
+      if (!wait) {
         const response = await fetch(
-          `http://localhost:${serverInfo.httpPort}/api/reviews/${lastGlobalSessionId}/context`,
-          {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify(payload)
-          }
+          `http://localhost:${serverInfo.httpPort}/api/reviews/${sessionId}/result`
         );
         if (!response.ok) {
-          throw new Error(`Server returned ${response.status}`);
+          throw new Error(`Session not found: ${sessionId}`);
         }
-        return {
-          content: [
-            {
-              type: "text",
-              text: "Context updated in DiffPrism session."
-            }
-          ]
-        };
+        const { result } = await response.json();
+        return result ? jsonResult(result) : jsonResult({ status: "pending", sessionId, message: "No decision yet." });
+      }
+      try {
+        return jsonResult(await waitForDecision(serverInfo, sessionId, Math.min(timeout ?? 300, 600) * 1e3));
       } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Error updating review context: ${message}`
-            }
-          ],
-          isError: true
-        };
+        if (err instanceof ReviewerAskedError) {
+          return reviewerAskedResult(err, "call get_review_result with wait: true again");
+        }
+        if (err instanceof ReviewTimeoutError) {
+          return jsonResult({
+            status: "pending",
+            sessionId,
+            message: "Still no decision; the review remains open in the reviewer's browser. Call get_review_result with wait: true again rather than asking the user \u2014 their decision is the answer."
+          });
+        }
+        throw err;
       }
-    }
+    })
   );
   server.tool(
-    "get_review_result",
-    "Fetch the most recent review result from a DiffPrism session. Returns the reviewer's decision and comments if a review has been submitted, or a message indicating no pending result. Use wait=true to block until a result is available \u2014 this is the standard way to wait for a reviewer's decision after calling open_review.",
+    "update_review_context",
+    "Push reasoning, title, or description to an open review without opening a new one. Returns immediately.",
     {
-      wait: z.boolean().optional().describe("If true, poll until a review result is available (blocks up to timeout)"),
-      timeout: z.number().optional().describe("Max wait time in seconds when wait=true (default: 300, max: 600)")
+      ...targetParams,
+      reasoning: z.string().optional().describe("Agent reasoning about the current changes"),
+      title: z.string().optional().describe("Updated title for the review"),
+      description: z.string().optional().describe("Updated description of the changes")
     },
-    async ({ wait, timeout }) => {
-      try {
-        const maxWaitMs = Math.min(timeout ?? 300, 600) * 1e3;
-        const pollIntervalMs = 2e3;
-        const serverInfo = lastGlobalServerInfo ?? await isServerAlive();
-        if (!serverInfo || !lastGlobalSessionId) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: "No DiffPrism session is running. Use `open_review` to start a review."
-              }
-            ]
-          };
-        }
-        if (wait) {
-          const start = Date.now();
-          while (Date.now() - start < maxWaitMs) {
-            const response2 = await fetch(
-              `http://localhost:${serverInfo.httpPort}/api/reviews/${lastGlobalSessionId}/result`
-            );
-            if (response2.ok) {
-              const data = await response2.json();
-              if (data.result) {
-                return {
-                  content: [
-                    {
-                      type: "text",
-                      text: JSON.stringify(data.result, null, 2)
-                    }
-                  ]
-                };
-              }
-            }
-            await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
-          }
-          return {
-            content: [
-              {
-                type: "text",
-                text: "No review result received within timeout."
-              }
-            ]
-          };
+    async ({ session_id, repo_path, reasoning, title, description }) => withSession({ session_id, repo_path }, async ({ serverInfo, sessionId }) => {
+      const payload = {};
+      if (reasoning !== void 0) payload.reasoning = reasoning;
+      if (title !== void 0) payload.title = title;
+      if (description !== void 0) payload.description = description;
+      const response = await fetch(
+        `http://localhost:${serverInfo.httpPort}/api/reviews/${sessionId}/context`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(payload)
         }
-        const response = await fetch(
-          `http://localhost:${serverInfo.httpPort}/api/reviews/${lastGlobalSessionId}/result`
-        );
-        if (response.ok) {
-          const data = await response.json();
-          if (data.result) {
-            return {
-              content: [
-                {
-                  type: "text",
-                  text: JSON.stringify(data.result, null, 2)
-                }
-              ]
-            };
-          }
-        }
-        return {
-          content: [
-            {
-              type: "text",
-              text: "No pending review result."
-            }
-          ]
-        };
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Error reading review result: ${message}`
-            }
-          ],
-          isError: true
-        };
+      );
+      if (!response.ok) {
+        return toolError(`Error updating review context: server returned ${response.status}`);
       }
-    }
+      return jsonResult({ sessionId, updated: Object.keys(payload) });
+    })
   );
   server.tool(
     "get_diff",
     "Get a structured diff (DiffSet) for local git changes. Returns file-level and hunk-level change data as JSON without opening a browser. Use this to inspect what changed before deciding whether to open a full review.",
     {
-      diff_ref: z.string().describe(
-        'Git diff reference: "staged", "unstaged", "working-copy" (staged+unstaged grouped), or a ref range like "HEAD~3..HEAD"'
-      )
+      diff_ref: diffRefParam
     },
-    async ({ diff_ref }) => {
+    async ({ diff_ref = DEFAULT_DIFF_REF }) => {
       try {
-        const cwd = process.cwd();
-        const { diffSet } = getDiff(diff_ref, { cwd });
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(diffSet, null, 2)
-            }
-          ]
-        };
+        const { diffSet } = getDiff(diff_ref, { cwd: process.cwd() });
+        return jsonResult(diffSet);
       } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Error: ${message}`
-            }
-          ],
-          isError: true
-        };
+        return toolError(`Error: ${errorMessage(err)}`);
       }
     }
   );
@@ -405,705 +277,302 @@ async function startMcpServer() {
     "analyze_diff",
     "Analyze local git changes and return a ReviewBriefing with summary, file triage (critical/notable/mechanical), impact detection (affected modules, tests, dependencies, breaking changes), complexity scores, test coverage gaps, and pattern flags (security issues, TODOs, console.logs). Same analysis shown in the DiffPrism briefing bar, but returned as JSON without opening a browser.",
     {
-      diff_ref: z.string().describe(
-        'Git diff reference: "staged", "unstaged", "working-copy" (staged+unstaged grouped), or a ref range like "HEAD~3..HEAD"'
-      )
+      diff_ref: diffRefParam
     },
-    async ({ diff_ref }) => {
+    async ({ diff_ref = DEFAULT_DIFF_REF }) => {
       try {
-        const cwd = process.cwd();
-        const { diffSet } = getDiff(diff_ref, { cwd });
+        const { diffSet } = getDiff(diff_ref, { cwd: process.cwd() });
         if (diffSet.files.length === 0) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: JSON.stringify({
-                  summary: "No changes to analyze.",
-                  triage: { critical: [], notable: [], mechanical: [] },
-                  impact: {
-                    affectedModules: [],
-                    affectedTests: [],
-                    publicApiChanges: false,
-                    breakingChanges: [],
-                    newDependencies: []
-                  },
-                  verification: { testsPass: null, typeCheck: null, lintClean: null },
-                  fileStats: []
-                }, null, 2)
-              }
-            ]
-          };
+          return jsonResult({
+            summary: "No changes to analyze.",
+            triage: { critical: [], notable: [], mechanical: [] },
+            impact: {
+              affectedModules: [],
+              affectedTests: [],
+              publicApiChanges: false,
+              breakingChanges: [],
+              newDependencies: []
+            },
+            verification: { testsPass: null, typeCheck: null, lintClean: null },
+            fileStats: []
+          });
         }
-        const briefing = analyze(diffSet);
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(briefing, null, 2)
-            }
-          ]
-        };
+        return jsonResult(analyze(diffSet));
       } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Error: ${message}`
-            }
-          ],
-          isError: true
-        };
+        return toolError(`Error: ${errorMessage(err)}`);
       }
     }
   );
   server.tool(
-    "add_annotation",
-    "Post a structured finding (annotation) to a review session. Use this to flag issues, suggest improvements, or ask questions about specific lines of code in a review. Requires a running global server (`diffprism server`).",
+    "annotate",
+    "Post findings to an open review. They appear inline on the diff in the DiffPrism dashboard in real time. Use type 'warning' for anything the reviewer must look at \u2014 warnings flag the session in the sidebar. Accepts one or many findings.",
     {
-      session_id: z.string().describe("Review session ID from open_review"),
-      file: z.string().describe("File path within the diff to annotate"),
-      line: z.number().describe("Line number to annotate"),
-      body: z.string().describe("The annotation text \u2014 your finding, suggestion, or question"),
-      type: z.enum(["finding", "suggestion", "question", "warning"]).describe("Type of annotation"),
-      confidence: z.number().min(0).max(1).optional().describe("Confidence in the finding (0-1, defaults to 1)"),
-      category: z.enum([
-        "security",
-        "performance",
-        "convention",
-        "correctness",
-        "complexity",
-        "test-coverage",
-        "documentation",
-        "other"
-      ]).optional().describe("Category of the finding (defaults to 'other')"),
-      source_agent: z.string().optional().describe("Agent identifier (e.g., 'security-reviewer')")
+      ...targetParams,
+      annotations: z.array(annotationSchema).min(1).describe("One or more findings to post"),
+      source_agent: z.string().optional().describe("Who is posting these, e.g. 'security-reviewer'")
     },
-    async ({
-      session_id,
-      file,
-      line,
-      body,
-      type,
-      confidence,
-      category,
-      source_agent
-    }) => {
-      try {
-        const serverInfo = await isServerAlive();
-        if (!serverInfo) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: "No global server running. Start one with `diffprism server`."
-              }
-            ],
-            isError: true
-          };
-        }
+    async ({ session_id, repo_path, annotations, source_agent }) => withSession({ session_id, repo_path }, async ({ serverInfo, sessionId }) => {
+      const annotationIds = [];
+      const failed = [];
+      for (const annotation of annotations) {
+        const line = annotation.line ?? 1;
         const response = await fetch(
-          `http://localhost:${serverInfo.httpPort}/api/reviews/${session_id}/annotations`,
+          `http://localhost:${serverInfo.httpPort}/api/reviews/${sessionId}/annotations`,
           {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({
-              file,
+              file: annotation.file,
               line,
-              body,
-              type,
-              confidence: confidence ?? 1,
-              category: category ?? "other",
-              source: {
-                agent: source_agent ?? "unknown",
-                tool: "add_annotation"
-              }
+              body: annotation.body,
+              type: annotation.type,
+              confidence: annotation.confidence ?? 1,
+              category: annotation.category ?? "other",
+              source: { agent: source_agent ?? "unknown", tool: "annotate" }
             })
           }
         );
-        if (!response.ok) {
-          const errorData = await response.json().catch(() => ({}));
-          const errorMsg = errorData.error ?? `Server returned ${response.status}`;
-          return {
-            content: [
-              {
-                type: "text",
-                text: `Error: ${errorMsg}`
-              }
-            ],
-            isError: true
-          };
+        if (response.ok) {
+          annotationIds.push((await response.json()).annotationId);
+        } else {
+          const data = await response.json().catch(() => ({}));
+          failed.push({
+            file: annotation.file,
+            line,
+            error: data.error ?? `Server returned ${response.status}`
+          });
         }
-        const data = await response.json();
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(
-                { annotationId: data.annotationId, sessionId: session_id },
-                null,
-                2
-              )
-            }
-          ]
-        };
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Error: ${message}`
-            }
-          ],
-          isError: true
-        };
       }
-    }
+      const result = { sessionId, annotationIds, ...failed.length > 0 ? { failed } : {} };
+      return annotationIds.length === 0 ? { ...jsonResult(result), isError: true } : jsonResult(result);
+    })
   );
   server.tool(
     "get_review_state",
-    "Get the current state of a review session including session summary and annotations. Returns session metadata, status, and any agent annotations. Use this to check on a review's progress or read agent findings.",
-    {
-      session_id: z.string().optional().describe(
-        "Review session ID. If omitted, uses the most recently created session."
-      )
-    },
-    async ({ session_id }) => {
-      try {
-        const sessionId = session_id ?? lastGlobalSessionId;
-        if (!sessionId) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: "No session ID provided and no recent session available."
-              }
-            ],
-            isError: true
-          };
-        }
-        const serverInfo = await isServerAlive();
-        if (!serverInfo) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: "No global server running. Start one with `diffprism server`."
-              }
-            ],
-            isError: true
-          };
-        }
-        const [sessionResponse, annotationsResponse] = await Promise.all([
-          fetch(
-            `http://localhost:${serverInfo.httpPort}/api/reviews/${sessionId}`
-          ),
-          fetch(
-            `http://localhost:${serverInfo.httpPort}/api/reviews/${sessionId}/annotations`
-          )
-        ]);
-        if (!sessionResponse.ok) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: `Session not found: ${sessionId}`
-              }
-            ],
-            isError: true
-          };
-        }
-        const session = await sessionResponse.json();
-        const annotations = annotationsResponse.ok ? await annotationsResponse.json() : { annotations: [] };
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(
-                {
-                  session,
-                  annotations: annotations.annotations
-                },
-                null,
-                2
-              )
-            }
-          ]
-        };
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Error: ${message}`
-            }
-          ],
-          isError: true
-        };
+    "Get the state of an open review: session summary (status, decision, whether it has new changes or needs attention) and all annotations.",
+    { ...targetParams },
+    async ({ session_id, repo_path }) => withSession({ session_id, repo_path }, async ({ serverInfo, sessionId }) => {
+      const [sessionResponse, annotationsResponse] = await Promise.all([
+        fetch(`http://localhost:${serverInfo.httpPort}/api/reviews/${sessionId}`),
+        fetch(`http://localhost:${serverInfo.httpPort}/api/reviews/${sessionId}/annotations`)
+      ]);
+      if (!sessionResponse.ok) {
+        return toolError(`Session not found: ${sessionId}`);
       }
-    }
+      const session = await sessionResponse.json();
+      const { annotations } = annotationsResponse.ok ? await annotationsResponse.json() : { annotations: [] };
+      return jsonResult({ session, annotations });
+    })
   );
   server.tool(
-    "flag_for_attention",
-    "Mark specific files in a review session for human attention. Posts warning annotations for each flagged file. Use this to highlight files that need careful human review. Requires a running global server (`diffprism server`).",
+    "get_review_comments",
+    "Get every thread on an open review \u2014 agent findings and the reviewer's comments, each with its replies. `awaitingReply` marks threads where the reviewer spoke last and nobody has answered. Read these before adding your own.",
     {
-      session_id: z.string().optional().describe(
-        "Review session ID. If omitted, uses the most recently created session."
-      ),
-      files: z.array(
-        z.object({
-          path: z.string().describe("File path to flag for attention"),
-          reason: z.string().describe("Why this file needs human attention"),
-          line: z.number().optional().describe("Specific line to highlight (defaults to 1)")
-        })
-      ).describe("Files to flag for human attention"),
-      source_agent: z.string().optional().describe("Agent identifier (e.g., 'security-reviewer')")
+      ...targetParams,
+      awaiting_reply: z.boolean().optional().describe("Only return threads waiting for an agent to reply")
     },
-    async ({ session_id, files, source_agent }) => {
-      try {
-        const sessionId = session_id ?? lastGlobalSessionId;
-        if (!sessionId) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: "No session ID provided and no recent session available."
-              }
-            ],
-            isError: true
-          };
-        }
-        const serverInfo = await isServerAlive();
-        if (!serverInfo) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: "No global server running. Start one with `diffprism server`."
-              }
-            ],
-            isError: true
-          };
-        }
-        let flagged = 0;
-        for (const file of files) {
-          const response = await fetch(
-            `http://localhost:${serverInfo.httpPort}/api/reviews/${sessionId}/annotations`,
-            {
-              method: "POST",
-              headers: { "Content-Type": "application/json" },
-              body: JSON.stringify({
-                file: file.path,
-                line: file.line ?? 1,
-                body: file.reason,
-                type: "warning",
-                confidence: 1,
-                category: "other",
-                source: {
-                  agent: source_agent ?? "flag_for_attention",
-                  tool: "flag_for_attention"
-                }
-              })
-            }
-          );
-          if (response.ok) {
-            flagged++;
-          }
-        }
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify({ flagged, sessionId }, null, 2)
-            }
-          ]
-        };
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Error: ${message}`
-            }
-          ],
-          isError: true
-        };
+    async ({ session_id, repo_path, awaiting_reply }) => withSession({ session_id, repo_path }, async ({ serverInfo, sessionId }) => {
+      const threads = await readThreads(serverInfo, sessionId);
+      if (!threads) {
+        return toolError(`Session not found: ${sessionId}`);
       }
-    }
+      const annotations = awaiting_reply ? threads.filter((t) => t.awaitingReply) : threads;
+      return jsonResult({ sessionId, annotations });
+    })
   );
   server.tool(
-    "get_pr_context",
-    "Get a high-level overview of the active PR review session. Returns PR metadata (title, author, branches, URL), review briefing summary, file list with stats, and local repo path. Use this to orient yourself before diving into specific files.",
+    "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.",
     {
-      session_id: z.string().optional().describe("Review session ID. If omitted, uses the most recently created session.")
+      ...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'")
     },
-    async ({ session_id }) => {
-      try {
-        const serverInfo = await isServerAlive();
-        if (!serverInfo) {
-          return {
-            content: [{ type: "text", text: "No global server running. Start one with `diffprism server`." }],
-            isError: true
-          };
-        }
-        const sessionId = await resolveSessionId(session_id, serverInfo);
-        if (!sessionId) {
-          return {
-            content: [{ type: "text", text: "No review session found. Open a PR review first with `diffprism review <PR URL>`." }],
-            isError: true
-          };
-        }
-        const response = await fetch(
-          `http://localhost:${serverInfo.httpPort}/api/reviews/${sessionId}/payload`
-        );
-        if (!response.ok) {
-          return {
-            content: [{ type: "text", text: `Session not found: ${sessionId}` }],
-            isError: true
-          };
+    async ({ session_id, repo_path, annotation_id, body, source_agent }) => withSession({ session_id, repo_path }, async ({ serverInfo, sessionId }) => {
+      const response = await fetch(
+        `http://localhost:${serverInfo.httpPort}/api/reviews/${sessionId}/annotations/${annotation_id}/replies`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ author: "agent", agent: source_agent ?? "unknown", body })
         }
-        const data = await response.json();
-        const { payload, projectPath } = data;
-        const result = {
-          sessionId,
-          projectPath,
-          localRepoConnected: !projectPath.startsWith("github:"),
-          pr: payload.metadata.githubPr ?? null,
-          title: payload.metadata.title,
-          description: payload.metadata.description,
-          briefingSummary: payload.briefing.summary,
-          triage: payload.briefing.triage,
-          files: payload.diffSet.files.map((f) => ({
-            path: f.path,
-            status: f.status,
-            additions: f.additions,
-            deletions: f.deletions,
-            language: f.language
-          })),
-          totalFiles: payload.diffSet.files.length
-        };
-        return {
-          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
-        };
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return {
-          content: [{ type: "text", text: `Error: ${message}` }],
-          isError: true
-        };
+      );
+      const data = await response.json().catch(() => ({}));
+      if (!response.ok) {
+        return toolError(`Error: ${data.error ?? `server returned ${response.status}`}`);
       }
-    }
+      return jsonResult({ sessionId, annotationId: annotation_id, replyId: data.replyId });
+    })
   );
   server.tool(
-    "get_file_diff",
-    "Get the diff hunks for a specific file in the active review session. Returns the file's changes (additions, deletions, hunks with line-level detail) and its briefing categorization. Use this to focus on one file at a time.",
+    "wait_for_comments",
+    "Wait for the reviewer to write something you haven't answered \u2014 a new comment on a line, or a reply in a thread. Returns those threads as soon as there are any. Use it to hold a conversation during a PR review: wait, answer each thread with `reply`, then wait again. If it returns `timed_out`, nothing new was said; wait again rather than asking the user in the terminal.",
     {
-      file: z.string().describe("File path within the diff (e.g., 'src/index.ts')"),
-      session_id: z.string().optional().describe("Review session ID. If omitted, uses the most recently created session.")
+      ...targetParams,
+      timeout: z.number().optional().describe(`Max wait in seconds (default ${DEFAULT_WAIT_MS / 1e3}, max 600)`)
     },
-    async ({ file, session_id }) => {
-      try {
-        const serverInfo = await isServerAlive();
-        if (!serverInfo) {
-          return {
-            content: [{ type: "text", text: "No global server running. Start one with `diffprism server`." }],
-            isError: true
-          };
-        }
-        const sessionId = await resolveSessionId(session_id, serverInfo);
-        if (!sessionId) {
-          return {
-            content: [{ type: "text", text: "No review session found. Open a PR review first with `diffprism review <PR URL>`." }],
-            isError: true
-          };
-        }
-        const response = await fetch(
-          `http://localhost:${serverInfo.httpPort}/api/reviews/${sessionId}/payload`
-        );
-        if (!response.ok) {
-          return {
-            content: [{ type: "text", text: `Session not found: ${sessionId}` }],
-            isError: true
-          };
-        }
-        const data = await response.json();
-        const diffFile = data.payload.diffSet.files.find((f) => f.path === file);
-        if (!diffFile) {
-          const available = data.payload.diffSet.files.map((f) => f.path);
-          return {
-            content: [{ type: "text", text: `File not found in diff: "${file}". Available files:
-${available.join("\n")}` }],
-            isError: true
-          };
+    async ({ session_id, repo_path, timeout }) => withSession({ session_id, repo_path }, async ({ serverInfo, sessionId }) => {
+      const maxWaitMs = Math.min(timeout ?? DEFAULT_WAIT_MS / 1e3, 600) * 1e3;
+      const start = Date.now();
+      while (true) {
+        const threads = await readThreads(serverInfo, sessionId);
+        if (!threads) {
+          return toolError(`Session not found: ${sessionId}`);
+        }
+        const waiting = threads.filter((t) => t.awaitingReply);
+        if (waiting.length > 0) {
+          return jsonResult({ sessionId, threads: waiting });
+        }
+        if (Date.now() - start >= maxWaitMs) {
+          return jsonResult({
+            status: "timed_out",
+            sessionId,
+            message: "The reviewer hasn't written anything new. Call wait_for_comments again to keep listening \u2014 don't ask them in the terminal."
+          });
         }
-        const { triage } = data.payload.briefing;
-        let category = "mechanical";
-        if (triage.critical.some((c) => c.file === file)) category = "critical";
-        else if (triage.notable.some((n) => n.file === file)) category = "notable";
-        return {
-          content: [{ type: "text", text: JSON.stringify({
-            path: diffFile.path,
-            oldPath: diffFile.oldPath,
-            status: diffFile.status,
-            language: diffFile.language,
-            additions: diffFile.additions,
-            deletions: diffFile.deletions,
-            triageCategory: category,
-            hunks: diffFile.hunks
-          }, null, 2) }]
-        };
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return {
-          content: [{ type: "text", text: `Error: ${message}` }],
-          isError: true
-        };
+        await new Promise((resolve) => setTimeout(resolve, 2e3));
       }
-    }
+    })
   );
   server.tool(
-    "get_file_context",
-    "Get the full content of a file from the local repository. Uses `git show` to read the file at the PR's head branch without switching branches. Requires the review session to be connected to a local repo (server must be running from within the repo clone).",
-    {
-      file: z.string().describe("File path relative to repo root (e.g., 'src/index.ts')"),
-      ref: z.string().optional().describe("Git ref to read from (e.g., 'origin/main', 'HEAD'). Defaults to the PR's head branch if available, otherwise HEAD."),
-      session_id: z.string().optional().describe("Review session ID. If omitted, uses the most recently created session.")
-    },
-    async ({ file, ref, session_id }) => {
-      try {
-        const serverInfo = await isServerAlive();
-        if (!serverInfo) {
-          return {
-            content: [{ type: "text", text: "No global server running. Start one with `diffprism server`." }],
-            isError: true
-          };
-        }
-        const sessionId = await resolveSessionId(session_id, serverInfo);
-        if (!sessionId) {
-          return {
-            content: [{ type: "text", text: "No review session found. Open a PR review first with `diffprism review <PR URL>`." }],
-            isError: true
-          };
-        }
-        const response = await fetch(
-          `http://localhost:${serverInfo.httpPort}/api/reviews/${sessionId}/payload`
-        );
-        if (!response.ok) {
-          return {
-            content: [{ type: "text", text: `Session not found: ${sessionId}` }],
-            isError: true
-          };
-        }
-        const data = await response.json();
-        if (data.projectPath.startsWith("github:")) {
-          return {
-            content: [{ type: "text", text: "No local repo connected. Run the server from within a local clone of the repository to enable file context." }],
-            isError: true
-          };
-        }
-        const gitRef = ref ?? (data.payload.metadata.githubPr?.headBranch ? `origin/${data.payload.metadata.githubPr.headBranch}` : "HEAD");
-        const { execSync } = await import("child_process");
-        let content;
-        try {
-          content = execSync(`git show ${gitRef}:${file}`, {
-            cwd: data.projectPath,
-            encoding: "utf-8",
-            stdio: ["pipe", "pipe", "pipe"],
-            maxBuffer: 10 * 1024 * 1024
-            // 10MB
-          });
-        } catch {
-          const fs = await import("fs");
-          const path = await import("path");
-          const filePath = path.join(data.projectPath, file);
-          try {
-            content = fs.readFileSync(filePath, "utf-8");
-          } catch {
-            return {
-              content: [{ type: "text", text: `File not found: "${file}" (tried git show ${gitRef}:${file} and working tree)` }],
-              isError: true
-            };
-          }
-        }
-        return {
-          content: [{ type: "text", text: JSON.stringify({
-            file,
-            ref: gitRef,
-            projectPath: data.projectPath,
-            content,
-            lineCount: content.split("\n").length
-          }, null, 2) }]
-        };
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return {
-          content: [{ type: "text", text: `Error: ${message}` }],
-          isError: true
-        };
+    "get_user_focus",
+    "Get what the reviewer is looking at right now in the DiffPrism dashboard \u2014 the selected file and any focused line range. Use this to answer questions about the code they are actively reviewing.",
+    { ...targetParams },
+    async ({ session_id, repo_path }) => withSession({ session_id, repo_path }, async ({ serverInfo, sessionId }) => {
+      const response = await fetch(
+        `http://localhost:${serverInfo.httpPort}/api/reviews/${sessionId}/focus`
+      );
+      if (!response.ok) {
+        return toolError(`Session not found: ${sessionId}`);
       }
-    }
+      const data = await response.json();
+      return jsonResult({ sessionId, ...data });
+    })
   );
   server.tool(
-    "add_review_comment",
-    "Post a review comment to the active session. The comment appears in the DiffPrism browser UI in real-time as an inline annotation on the diff. Use this to leave findings, suggestions, or questions about specific lines of code.",
-    {
-      file: z.string().describe("File path within the diff"),
-      line: z.number().describe("Line number to comment on"),
-      body: z.string().describe("The comment text"),
-      type: z.enum(["comment", "suggestion", "concern"]).optional().describe("Type of comment (default: 'comment')"),
-      session_id: z.string().optional().describe("Review session ID. If omitted, uses the most recently created session.")
-    },
-    async ({ file, line, body, type, session_id }) => {
-      try {
-        const serverInfo = await isServerAlive();
-        if (!serverInfo) {
-          return {
-            content: [{ type: "text", text: "No global server running. Start one with `diffprism server`." }],
-            isError: true
-          };
-        }
-        const sessionId = await resolveSessionId(session_id, serverInfo);
-        if (!sessionId) {
-          return {
-            content: [{ type: "text", text: "No review session found. Open a PR review first with `diffprism review <PR URL>`." }],
-            isError: true
-          };
-        }
-        const annotationType = type === "concern" ? "warning" : type === "suggestion" ? "suggestion" : "finding";
-        const response = await fetch(
-          `http://localhost:${serverInfo.httpPort}/api/reviews/${sessionId}/annotations`,
-          {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({
-              file,
-              line,
-              body,
-              type: annotationType,
-              confidence: 1,
-              category: "other",
-              source: {
-                agent: "ai-reviewer",
-                tool: "add_review_comment"
-              }
-            })
-          }
-        );
-        if (!response.ok) {
-          const errorData = await response.json().catch(() => ({}));
-          return {
-            content: [{ type: "text", text: `Error: ${errorData.error ?? `Server returned ${response.status}`}` }],
-            isError: true
-          };
-        }
-        const data = await response.json();
-        return {
-          content: [{ type: "text", text: JSON.stringify({ annotationId: data.annotationId, sessionId }, null, 2) }]
-        };
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return {
-          content: [{ type: "text", text: `Error: ${message}` }],
-          isError: true
-        };
+    "get_pr_context",
+    "Get an overview of an open PR review: PR metadata (title, author, branches, URL), briefing summary, file list with stats, and the local repo path. Orient yourself with this before reading individual files. Open the PR review first with `diffprism review <PR URL>` or the dashboard.",
+    { ...targetParams },
+    async ({ session_id, repo_path }) => withSession({ session_id, repo_path }, async ({ serverInfo, sessionId }) => {
+      const response = await fetch(
+        `http://localhost:${serverInfo.httpPort}/api/reviews/${sessionId}/payload`
+      );
+      if (!response.ok) {
+        return toolError(`Session not found: ${sessionId}`);
       }
-    }
+      const { payload, projectPath } = await response.json();
+      return jsonResult({
+        sessionId,
+        projectPath,
+        localRepoConnected: !projectPath.startsWith("github:"),
+        pr: payload.metadata.githubPr ?? null,
+        title: payload.metadata.title,
+        description: payload.metadata.description,
+        briefingSummary: payload.briefing.summary,
+        triage: payload.briefing.triage,
+        files: payload.diffSet.files.map((f) => ({
+          path: f.path,
+          status: f.status,
+          additions: f.additions,
+          deletions: f.deletions,
+          language: f.language
+        })),
+        totalFiles: payload.diffSet.files.length
+      });
+    })
   );
   server.tool(
-    "get_review_comments",
-    "Get all comments and annotations on the active review session. Returns findings from agents and inline comments from human reviewers. Use this to see what has already been noted before adding your own comments.",
+    "get_file_diff",
+    "Get the diff hunks for one file in an open review, with its triage category. Use this to work through a review one file at a time.",
     {
-      session_id: z.string().optional().describe("Review session ID. If omitted, uses the most recently created session.")
+      file: z.string().describe("File path within the diff (e.g., 'src/index.ts')"),
+      ...targetParams
     },
-    async ({ session_id }) => {
-      try {
-        const serverInfo = await isServerAlive();
-        if (!serverInfo) {
-          return {
-            content: [{ type: "text", text: "No global server running. Start one with `diffprism server`." }],
-            isError: true
-          };
-        }
-        const sessionId = await resolveSessionId(session_id, serverInfo);
-        if (!sessionId) {
-          return {
-            content: [{ type: "text", text: "No review session found. Open a PR review first with `diffprism review <PR URL>`." }],
-            isError: true
-          };
-        }
-        const response = await fetch(
-          `http://localhost:${serverInfo.httpPort}/api/reviews/${sessionId}/annotations`
-        );
-        if (!response.ok) {
-          return {
-            content: [{ type: "text", text: `Session not found: ${sessionId}` }],
-            isError: true
-          };
-        }
-        const data = await response.json();
-        return {
-          content: [{ type: "text", text: JSON.stringify({ sessionId, annotations: data.annotations }, null, 2) }]
-        };
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return {
-          content: [{ type: "text", text: `Error: ${message}` }],
-          isError: true
-        };
+    async ({ file, session_id, repo_path }) => withSession({ session_id, repo_path }, async ({ serverInfo, sessionId }) => {
+      const response = await fetch(
+        `http://localhost:${serverInfo.httpPort}/api/reviews/${sessionId}/payload`
+      );
+      if (!response.ok) {
+        return toolError(`Session not found: ${sessionId}`);
       }
-    }
+      const data = await response.json();
+      const diffFile = data.payload.diffSet.files.find((f) => f.path === file);
+      if (!diffFile) {
+        const available = data.payload.diffSet.files.map((f) => f.path);
+        return toolError(`File not found in diff: "${file}". Available files:
+${available.join("\n")}`);
+      }
+      const { triage } = data.payload.briefing;
+      let triageCategory = "mechanical";
+      if (triage.critical.some((c) => c.file === file)) triageCategory = "critical";
+      else if (triage.notable.some((n) => n.file === file)) triageCategory = "notable";
+      return jsonResult({
+        path: diffFile.path,
+        oldPath: diffFile.oldPath,
+        status: diffFile.status,
+        language: diffFile.language,
+        additions: diffFile.additions,
+        deletions: diffFile.deletions,
+        triageCategory,
+        hunks: diffFile.hunks
+      });
+    })
   );
   server.tool(
-    "get_user_focus",
-    "Get what the user is currently looking at in the DiffPrism review UI. Returns the file they have selected and any line range they are focused on. Use this to provide context-aware help \u2014 answer questions about the code the user is actively reviewing.",
+    "get_file_context",
+    "Get the full content of a file from the review's local repository, read with `git show` at the PR's head branch without switching branches. Needs the review to be connected to a local clone.",
     {
-      session_id: z.string().optional().describe("Review session ID. If omitted, uses the most recently created session.")
+      file: z.string().describe("File path relative to repo root (e.g., 'src/index.ts')"),
+      ref: z.string().optional().describe("Git ref to read from (e.g., 'origin/main', 'HEAD'). Defaults to the PR's head branch if available, otherwise HEAD."),
+      ...targetParams
     },
-    async ({ session_id }) => {
-      try {
-        const serverInfo = await isServerAlive();
-        if (!serverInfo) {
-          return {
-            content: [{ type: "text", text: "No global server running. Start one with `diffprism server`." }],
-            isError: true
-          };
-        }
-        const sessionId = await resolveSessionId(session_id, serverInfo);
-        if (!sessionId) {
-          return {
-            content: [{ type: "text", text: "No review session found. Open a PR review first with `diffprism review <PR URL>`." }],
-            isError: true
-          };
-        }
-        const response = await fetch(
-          `http://localhost:${serverInfo.httpPort}/api/reviews/${sessionId}/focus`
+    async ({ file, ref, session_id, repo_path }) => withSession({ session_id, repo_path }, async ({ serverInfo, sessionId }) => {
+      const response = await fetch(
+        `http://localhost:${serverInfo.httpPort}/api/reviews/${sessionId}/payload`
+      );
+      if (!response.ok) {
+        return toolError(`Session not found: ${sessionId}`);
+      }
+      const data = await response.json();
+      if (data.projectPath.startsWith("github:")) {
+        return toolError(
+          "No local repo connected. Run the server from within a local clone of the repository to enable file context."
         );
-        if (!response.ok) {
-          return {
-            content: [{ type: "text", text: `Session not found: ${sessionId}` }],
-            isError: true
-          };
+      }
+      const gitRef = ref ?? (data.payload.metadata.githubPr?.headBranch ? `origin/${data.payload.metadata.githubPr.headBranch}` : "HEAD");
+      const { execSync } = await import("child_process");
+      let content;
+      try {
+        content = execSync(`git show ${gitRef}:${file}`, {
+          cwd: data.projectPath,
+          encoding: "utf-8",
+          stdio: ["pipe", "pipe", "pipe"],
+          maxBuffer: 10 * 1024 * 1024
+        });
+      } catch {
+        const fs = await import("fs");
+        const path = await import("path");
+        try {
+          content = fs.readFileSync(path.join(data.projectPath, file), "utf-8");
+        } catch {
+          return toolError(`File not found: "${file}" (tried git show ${gitRef}:${file} and working tree)`);
         }
-        const data = await response.json();
-        return {
-          content: [{ type: "text", text: JSON.stringify({ sessionId, ...data }, null, 2) }]
-        };
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return {
-          content: [{ type: "text", text: `Error: ${message}` }],
-          isError: true
-        };
       }
-    }
+      return jsonResult({
+        file,
+        ref: gitRef,
+        projectPath: data.projectPath,
+        content,
+        lineCount: content.split("\n").length
+      });
+    })
   );
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }
 export {
+  DEFAULT_WAIT_MS,
+  resolveTarget,
   startMcpServer
 };