second-opinion-mcp 0.2.0 → 0.3.0

package/README.md

@@ -33,6 +33,7 @@ Second Opinion reads your Claude Code session to understand what you're working
 - **Dependents** — Files that import your modified code
 - **Tests** — Test files related to your changes
 - **Types** — TypeScript/JSDoc type definitions
+- **Pull request** — PR metadata, comments, reviews, and changed files (requires `gh` CLI)
 
 ### Custom Tasks
 
@@ -377,6 +378,7 @@ When calling the MCP tool directly:
 - Node.js 18+
 - Claude Code CLI
 - At least one API key (Gemini or OpenAI)
+- [GitHub CLI (`gh`)](https://cli.github.com/) — optional, required for PR context detection
 
 ## License
 

package/dist/config.js

@@ -8,7 +8,7 @@ export const ConfigSchema = z.object({
     defaultProvider: z.enum(["gemini", "openai"]).default("gemini"),
     geminiModel: z.string().default("gemini-3-flash-preview"),
     openaiModel: z.string().default("gpt-5.2"),
-    maxContextTokens: z.number().default(100000),
+    maxContextTokens: z.number().default(200000),
     reviewsDir: z.string().default("second-opinions"),
     /** Default temperature for LLM generation (0-1) */
     temperature: z.number().min(0).max(1).default(0.3),
@@ -74,13 +74,14 @@ export function loadReviewInstructions(projectPath) {
     // Default instructions
     return `# Code Review Instructions
 
-You are a code reviewer providing a second opinion on code changes.
+You are a senior code reviewer providing a second opinion on code changes. Look beyond the immediate diff.
 
 ## Your Role
 - Review the code changes objectively
 - Identify potential issues, bugs, or improvements
 - Be constructive and specific in your feedback
 - Consider security, performance, and maintainability
+- Ask "what would have to be true for this problem not to exist?" — flag when complexity is a symptom of an upstream design choice
 
 ## Review Focus
 - Security vulnerabilities and best practices
@@ -88,12 +89,14 @@ You are a code reviewer providing a second opinion on code changes.
 - Code clarity and maintainability
 - Error handling and edge cases
 - Testing coverage
+- Upstream/downstream design opportunities: would a different API contract, tighter type, or removed abstraction simplify this code?
 
 ## Output Format
 Structure your review with:
 1. **Summary** (2-3 sentences overview)
 2. **Critical Issues** (if any - things that must be fixed)
 3. **Suggestions** (improvements that would be nice)
-4. **What's Done Well** (positive feedback)
+4. **Upstream/Downstream Opportunities** (changes outside the diff that could improve the design — label each Safe / Worth Investigating / Bold)
+5. **What's Done Well** (positive feedback)
 `;
 }

package/dist/context/bundler.d.ts

@@ -13,11 +13,12 @@ export interface BundleOptions {
     includeFiles?: string[];
     allowExternalFiles?: boolean;
     maxTokens?: number;
+    prNumber?: number;
 }
 export interface FileEntry {
     path: string;
     content: string;
-    category: "session" | "git" | "dependency" | "dependent" | "test" | "type" | "explicit";
+    category: "session" | "pr" | "git" | "dependency" | "dependent" | "test" | "type" | "explicit";
     tokenEstimate: number;
 }
 export interface OmittedFile {
@@ -36,11 +37,21 @@ export interface BudgetWarning {
 }
 export interface ContextBundle {
     conversationContext: string;
+    /** Formatted PR metadata markdown (title, body, comments, reviews) */
+    prContext?: string;
+    /** Raw PR metadata for structured access (egress summary, etc.) */
+    prMetadata?: {
+        number: number;
+        url: string;
+        commentsCount: number;
+        reviewsCount: number;
+    };
     files: FileEntry[];
     omittedFiles: OmittedFile[];
     totalTokens: number;
     categories: {
         session: number;
+        pr: number;
         git: number;
         dependency: number;
         dependent: number;
@@ -55,6 +66,11 @@ export interface ContextBundle {
     };
     /** Warnings about high-priority files being omitted due to budget */
     budgetWarnings: BudgetWarning[];
+    /** Set when PR detection failed for a non-trivial reason (not "no PR found") */
+    prDetectionFailure?: {
+        reason: string;
+        message: string;
+    };
 }
 /**
  * Collect and bundle all context for review

package/dist/context/bundler.js

@@ -3,6 +3,7 @@ import * as path from "path";
 import * as os from "os";
 import { parseSession, findLatestSession, formatConversationContext, } from "./session.js";
 import { getAllModifiedFiles } from "./git.js";
+import { detectPR, formatPRMetadata } from "./pr.js";
 import { getDependenciesForFiles, getDependentsForFiles, isWithinProject, } from "./imports.js";
 import { findTestFilesForFiles } from "./tests.js";
 import { findTypeFilesForFiles } from "./types.js";
@@ -189,7 +190,7 @@ function readFileEntry(filePath, category, existingContent) {
  * Collect and bundle all context for review
  */
 export async function bundleContext(options) {
-    const { projectPath, sessionId, includeConversation = true, includeDependencies = true, includeDependents = true, includeTests = true, includeTypes = true, includeFiles = [], allowExternalFiles = false, maxTokens = 100000, } = options;
+    const { projectPath, sessionId, includeConversation = true, includeDependencies = true, includeDependents = true, includeTests = true, includeTypes = true, includeFiles = [], allowExternalFiles = false, maxTokens = 100000, prNumber, } = options;
     const bundle = {
         conversationContext: "",
         files: [],
@@ -197,6 +198,7 @@ export async function bundleContext(options) {
         totalTokens: 0,
         categories: {
             session: 0,
+            pr: 0,
             git: 0,
             dependency: 0,
             dependent: 0,
@@ -210,11 +212,8 @@ export async function bundleContext(options) {
         },
         budgetWarnings: [],
     };
-    // Track files we've already added
     const addedFiles = new Set();
-    // Track redaction types across all files
     const allRedactedTypes = new Set();
-    // Helper to accumulate redaction stats
     const accumulateRedactionStats = (result) => {
         bundle.redactionStats.totalCount += result.redactionCount;
         for (const type of result.redactedTypes) {
@@ -236,15 +235,10 @@ export async function bundleContext(options) {
         remainingBudget -= conversationTokens;
     }
     // Calculate base budget for each category (used for spillover calculation)
-    const baseBudgets = {
-        explicit: Math.floor(remainingBudget * BUDGET_ALLOCATION.explicit),
-        session: Math.floor(remainingBudget * BUDGET_ALLOCATION.session),
-        git: Math.floor(remainingBudget * BUDGET_ALLOCATION.git),
-        dependency: Math.floor(remainingBudget * BUDGET_ALLOCATION.dependency),
-        dependent: Math.floor(remainingBudget * BUDGET_ALLOCATION.dependent),
-        test: Math.floor(remainingBudget * BUDGET_ALLOCATION.test),
-        type: Math.floor(remainingBudget * BUDGET_ALLOCATION.type),
-    };
+    const baseBudgets = Object.fromEntries(Object.entries(BUDGET_ALLOCATION).map(([cat, pct]) => [
+        cat,
+        Math.floor(remainingBudget * pct),
+    ]));
     // Track spillover budget from underutilized categories
     let spilloverBudget = 0;
     // Track omitted files per category for budget warnings
@@ -363,6 +357,57 @@ export async function bundleContext(options) {
     const sessionBudget = baseBudgets.session + Math.floor(spilloverBudget * 0.5);
     const sessionUsed = addFilesWithBudget(sessionFiles, "session", sessionBudget);
     getBudgetWithSpillover("session", sessionUsed);
+    // 2b. PR context (auto-detected or explicit prNumber)
+    const prDetection = detectPR(projectPath, prNumber);
+    if (prDetection.ok) {
+        const prContext = prDetection.pr;
+        // Format PR metadata and subtract from remaining budget
+        const prMetadata = formatPRMetadata(prContext);
+        const prMetadataTokens = estimateTokens(prMetadata);
+        bundle.prContext = prMetadata;
+        bundle.prMetadata = {
+            number: prContext.number,
+            url: prContext.url,
+            commentsCount: prContext.comments.length,
+            reviewsCount: prContext.reviews.length,
+        };
+        bundle.totalTokens += prMetadataTokens;
+        // Read PR changed files (with path validation)
+        const prFiles = [];
+        for (const filePath of prContext.changedFiles) {
+            if (addedFiles.has(filePath))
+                continue;
+            const normalizedPath = path.normalize(filePath);
+            if (isSensitivePath(normalizedPath)) {
+                bundle.omittedFiles.push({ path: filePath, category: "pr", tokenEstimate: 0, reason: "sensitive_path" });
+                continue;
+            }
+            if (!isWithinProject(normalizedPath, projectPath)) {
+                bundle.omittedFiles.push({ path: filePath, category: "pr", tokenEstimate: 0, reason: "outside_project" });
+                continue;
+            }
+            const result = readFileEntry(filePath, "pr");
+            if (result.entry) {
+                prFiles.push(result.entry);
+                accumulateRedactionStats(result);
+                modifiedFiles.push(filePath);
+            }
+        }
+        // Sort by token count (smaller files first to fit more)
+        prFiles.sort((a, b) => a.tokenEstimate - b.tokenEstimate);
+        // Process PR files with spillover
+        const prBudget = baseBudgets.pr + Math.floor(spilloverBudget * 0.5);
+        const prUsed = addFilesWithBudget(prFiles, "pr", prBudget);
+        getBudgetWithSpillover("pr", prUsed);
+    }
+    else {
+        // Surface failure reason (except no_pr_found which is normal)
+        if (prDetection.reason !== "no_pr_found") {
+            bundle.prDetectionFailure = { reason: prDetection.reason, message: prDetection.message };
+        }
+        // No PR — spillover the full pr budget to later categories
+        getBudgetWithSpillover("pr", 0);
+    }
     // 3. Git changes not in session
     const gitChangedFiles = getAllModifiedFiles(projectPath);
     const gitFiles = [];
@@ -506,10 +551,16 @@ export function formatBundleAsMarkdown(bundle, projectPath) {
         lines.push(bundle.conversationContext);
         lines.push("---\n");
     }
+    // PR context (metadata: title, body, comments, reviews)
+    if (bundle.prContext) {
+        lines.push(bundle.prContext);
+        lines.push("---\n");
+    }
     // Group files by category
     const categories = {
         explicit: [],
         session: [],
+        pr: [],
         git: [],
         dependency: [],
         dependent: [],
@@ -522,6 +573,7 @@ export function formatBundleAsMarkdown(bundle, projectPath) {
     const categoryLabels = {
         explicit: "Explicitly Included Files",
         session: "Modified Files (from Claude session)",
+        pr: "Pull Request Changed Files",
         git: "Additional Git Changes",
         dependency: "Dependencies (files imported by modified code)",
         dependent: "Dependents (files that import modified code)",

package/dist/context/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./session.js";
 export * from "./git.js";
+export * from "./pr.js";
 export * from "./imports.js";
 export * from "./tests.js";
 export * from "./types.js";

package/dist/context/index.js

@@ -1,5 +1,6 @@
 export * from "./session.js";
 export * from "./git.js";
+export * from "./pr.js";
 export * from "./imports.js";
 export * from "./tests.js";
 export * from "./types.js";

package/dist/context/pr.d.ts

@@ -0,0 +1,51 @@
+export interface PRComment {
+    author: string;
+    body: string;
+    createdAt: string;
+}
+export interface PRReview {
+    author: string;
+    body: string;
+    state: string;
+    createdAt: string;
+}
+export interface PRContext {
+    number: number;
+    title: string;
+    body: string;
+    url: string;
+    state: string;
+    baseBranch: string;
+    headBranch: string;
+    labels: string[];
+    comments: PRComment[];
+    reviews: PRReview[];
+    changedFiles: string[];
+}
+export type PRDetectionResult = {
+    ok: true;
+    pr: PRContext;
+} | {
+    ok: false;
+    reason: "gh_not_installed" | "gh_command_failed" | "no_pr_found" | "parse_error";
+    message: string;
+};
+/**
+ * Check if the GitHub CLI (gh) is installed and accessible
+ */
+export declare function isGhAvailable(): boolean;
+/**
+ * Detect a PR associated with the current branch or a specific PR number.
+ * Returns a discriminated union with failure reason on error.
+ */
+export declare function detectPR(projectPath: string, prNumber?: number): PRDetectionResult;
+/**
+ * Get changed files between the PR base branch and HEAD via git diff.
+ * Fallback/complement to the files field from gh pr view.
+ */
+export declare function getPRChangedFiles(projectPath: string, baseBranch: string): string[];
+/**
+ * Format PR metadata (title, body, comments, reviews) as markdown.
+ * All text content is run through redactSecrets before inclusion.
+ */
+export declare function formatPRMetadata(pr: PRContext): string;

package/dist/context/pr.js

@@ -0,0 +1,141 @@
+import { spawnSync } from "child_process";
+import * as path from "path";
+import { redactSecrets } from "../security/redactor.js";
+const SPAWN_OPTS = {
+    encoding: "utf-8",
+    stdio: ["pipe", "pipe", "pipe"],
+};
+/**
+ * Check if the GitHub CLI (gh) is installed and accessible
+ */
+export function isGhAvailable() {
+    return spawnSync("gh", ["--version"], SPAWN_OPTS).status === 0;
+}
+/**
+ * Detect a PR associated with the current branch or a specific PR number.
+ * Returns a discriminated union with failure reason on error.
+ */
+export function detectPR(projectPath, prNumber) {
+    if (!isGhAvailable()) {
+        return {
+            ok: false,
+            reason: "gh_not_installed",
+            message: "GitHub CLI (gh) is not installed. Install from https://cli.github.com/ for PR context detection.",
+        };
+    }
+    try {
+        const fields = "number,title,body,url,state,baseRefName,headRefName,labels,comments,reviews,files";
+        const args = prNumber
+            ? ["pr", "view", String(prNumber), "--json", fields]
+            : ["pr", "view", "--json", fields];
+        const result = spawnSync("gh", args, { cwd: projectPath, ...SPAWN_OPTS });
+        if (result.error || result.status !== 0) {
+            const stderr = (result.stderr || "").trim();
+            // "no pull requests found" is a normal condition, not an error
+            if (stderr.includes("no pull requests found") || stderr.includes("Could not resolve")) {
+                return { ok: false, reason: "no_pr_found", message: "No pull request found for the current branch." };
+            }
+            return {
+                ok: false,
+                reason: "gh_command_failed",
+                message: `gh pr view failed: ${stderr.slice(0, 200)}`,
+            };
+        }
+        const data = JSON.parse(result.stdout);
+        const pr = {
+            number: data.number,
+            title: data.title || "",
+            body: data.body || "",
+            url: data.url || "",
+            state: data.state || "",
+            baseBranch: data.baseRefName || "",
+            headBranch: data.headRefName || "",
+            labels: (data.labels || []).map((l) => l.name || ""),
+            comments: (data.comments || []).map((c) => ({
+                author: c.author?.login || "unknown",
+                body: c.body || "",
+                createdAt: c.createdAt || "",
+            })),
+            reviews: (data.reviews || []).map((r) => ({
+                author: r.author?.login || "unknown",
+                body: r.body || "",
+                state: r.state || "COMMENTED",
+                createdAt: r.createdAt || "",
+            })),
+            changedFiles: (data.files || [])
+                .map((f) => f.path)
+                .filter(Boolean)
+                .map((p) => path.join(projectPath, p)),
+        };
+        // Fallback: if gh returned no files but we have a base branch, use git diff
+        if (pr.changedFiles.length === 0 && pr.baseBranch) {
+            pr.changedFiles = getPRChangedFiles(projectPath, pr.baseBranch);
+        }
+        return { ok: true, pr };
+    }
+    catch {
+        return { ok: false, reason: "parse_error", message: "Failed to parse gh pr view output." };
+    }
+}
+/**
+ * Get changed files between the PR base branch and HEAD via git diff.
+ * Fallback/complement to the files field from gh pr view.
+ */
+export function getPRChangedFiles(projectPath, baseBranch) {
+    try {
+        const result = spawnSync("git", ["diff", `${baseBranch}...HEAD`, "--name-only"], { cwd: projectPath, ...SPAWN_OPTS });
+        if (result.error || result.status !== 0) {
+            return [];
+        }
+        return result.stdout
+            .split("\n")
+            .filter(Boolean)
+            .map((f) => path.join(projectPath, f));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Format PR metadata (title, body, comments, reviews) as markdown.
+ * All text content is run through redactSecrets before inclusion.
+ */
+export function formatPRMetadata(pr) {
+    const lines = [];
+    lines.push(`## Pull Request #${pr.number}\n`);
+    lines.push(`**${redactSecrets(pr.title).content}**\n`);
+    lines.push(`- **URL:** ${pr.url}`);
+    lines.push(`- **State:** ${pr.state}`);
+    lines.push(`- **Base:** ${pr.baseBranch} ← **Head:** ${pr.headBranch}`);
+    if (pr.labels.length > 0) {
+        lines.push(`- **Labels:** ${pr.labels.join(", ")}`);
+    }
+    lines.push("");
+    // PR body
+    if (pr.body) {
+        lines.push("### Description\n");
+        lines.push(redactSecrets(pr.body).content);
+        lines.push("");
+    }
+    // Discussion comments
+    if (pr.comments.length > 0) {
+        lines.push("### Discussion Comments\n");
+        for (const comment of pr.comments) {
+            lines.push(`**${comment.author}** (${comment.createdAt}):`);
+            lines.push(redactSecrets(comment.body).content);
+            lines.push("");
+        }
+    }
+    // Reviews
+    if (pr.reviews.length > 0) {
+        lines.push("### Reviews\n");
+        for (const review of pr.reviews) {
+            lines.push(`**${review.author}** — ${review.state} (${review.createdAt}):`);
+            if (review.body) {
+                lines.push(redactSecrets(review.body).content);
+            }
+            lines.push("");
+        }
+    }
+    return lines.join("\n");
+}

package/dist/output/writer.d.ts

@@ -23,6 +23,13 @@ export interface EgressSummary {
         totalCount: number;
         types: string[];
     };
+    /** PR context metadata when reviewing a pull request */
+    prContext?: {
+        prNumber: number;
+        prUrl: string;
+        commentsIncluded: number;
+        reviewsIncluded: number;
+    };
 }
 /**
  * Write a review/response to a markdown file

package/dist/providers/base.d.ts

@@ -6,8 +6,6 @@ export interface ReviewRequest {
     customPrompt?: string;
     /** Temperature for LLM generation (0-1). Lower = more focused, higher = more creative. */
     temperature?: number;
-    /** Whether files were omitted from context due to budget constraints */
-    hasOmittedFiles?: boolean;
 }
 export interface ReviewResponse {
     review: string;
@@ -20,9 +18,8 @@ export interface ReviewProvider {
 }
 /**
  * Get the system prompt based on whether a custom task is provided
- * and whether files were omitted from context
  */
-export declare function getSystemPrompt(hasTask: boolean, hasOmittedFiles?: boolean): string;
+export declare function getSystemPrompt(hasTask: boolean): string;
 /**
  * Build the full prompt for the LLM
  */

package/dist/providers/base.js

@@ -1,31 +1,27 @@
 /**
- * Calibration text for when files were omitted due to budget constraints
+ * Verification instructions appended to every system prompt to prevent hallucinated claims.
+ * Always included regardless of whether files were omitted — models can fabricate issues
+ * even when the relevant code is in context.
  */
-const CONTEXT_CALIBRATION = `
+const VERIFICATION_REQUIREMENTS = `
 
-## Important: Context Limitations
+## Important: Verification Requirements
 
-This review is based on a subset of the codebase. Some files were omitted due to token limits.
-
-When reviewing:
+When reviewing, you MUST verify claims against the provided code:
 1. Only report issues you can VERIFY in the provided code
-2. If you suspect an issue but cannot see the relevant implementation, mark it as:
-   "⚠️ UNVERIFIED: [description] - relevant code not in context"
-3. Do NOT assume missing code is actually missing from the codebase
-4. Check the "Omitted Files" section before flagging missing implementations`;
+2. For Critical Issues, QUOTE the specific code that demonstrates the problem
+3. If you suspect an issue but cannot find confirming code, mark it as:
+   "⚠️ UNVERIFIED: [description] - could not locate confirming code"
+4. Do NOT assume code is missing or broken without evidence
+5. Search the full provided context before claiming something doesn't exist`;
 /**
  * Get the system prompt based on whether a custom task is provided
- * and whether files were omitted from context
  */
-export function getSystemPrompt(hasTask, hasOmittedFiles) {
-    let prompt = hasTask
-        ? "You are an expert software engineer. Complete the requested task thoroughly and provide clear, actionable output."
-        : "You are an expert software engineer performing a code review. Be thorough, constructive, and actionable.";
-    // Add calibration when files were omitted
-    if (hasOmittedFiles) {
-        prompt += CONTEXT_CALIBRATION;
-    }
-    return prompt;
+export function getSystemPrompt(hasTask) {
+    const base = hasTask
+        ? "You are a senior software engineer. Complete the requested task thoroughly and provide clear, actionable output. When relevant, consider whether changes upstream or downstream of the immediate scope would produce a better outcome."
+        : "You are a senior software engineer performing a code review. You have seen systems like this evolve over years. Be thorough, constructive, and actionable. Look beyond the immediate diff — consider whether the right change might be above or below the code under review.";
+    return base + VERIFICATION_REQUIREMENTS;
 }
 /**
  * Build the full prompt for the LLM

package/dist/providers/gemini.js

@@ -10,7 +10,7 @@ export class GeminiProvider {
     }
     async review(request) {
         const prompt = buildReviewPrompt(request);
-        const systemInstruction = getSystemPrompt(!!request.task, request.hasOmittedFiles);
+        const systemInstruction = getSystemPrompt(!!request.task);
         const model = this.client.getGenerativeModel({
             model: this.model,
             systemInstruction,

package/dist/providers/openai.js

@@ -10,7 +10,7 @@ export class OpenAIProvider {
     }
     async review(request) {
         const prompt = buildReviewPrompt(request);
-        const systemPrompt = getSystemPrompt(!!request.task, request.hasOmittedFiles);
+        const systemPrompt = getSystemPrompt(!!request.task);
         // Use provided temperature or default to 0.3 for focused output
         const temperature = request.temperature ?? 0.3;
         const response = await this.client.chat.completions.create({

package/dist/server.js

@@ -77,6 +77,10 @@ The reviewer sees the same context Claude had, plus related code for full unders
                                 default: 100000,
                                 description: "Maximum tokens for context",
                             },
+                            prNumber: {
+                                type: "number",
+                                description: "PR number to review. Auto-detects from current branch if omitted.",
+                            },
                             sessionName: {
                                 type: "string",
                                 description: "Name for this review (used in output filename)",

package/dist/tools/review.d.ts

@@ -14,6 +14,7 @@ export declare const SecondOpinionInputSchema: z.ZodObject<{
     includeTests: z.ZodDefault<z.ZodBoolean>;
     includeTypes: z.ZodDefault<z.ZodBoolean>;
     maxTokens: z.ZodDefault<z.ZodNumber>;
+    prNumber: z.ZodOptional<z.ZodNumber>;
     temperature: z.ZodOptional<z.ZodNumber>;
     sessionName: z.ZodOptional<z.ZodString>;
     customPrompt: z.ZodOptional<z.ZodString>;
@@ -33,6 +34,7 @@ export declare const SecondOpinionInputSchema: z.ZodObject<{
     temperature?: number | undefined;
     sessionId?: string | undefined;
     includeFiles?: string[] | undefined;
+    prNumber?: number | undefined;
     task?: string | undefined;
     sessionName?: string | undefined;
     customPrompt?: string | undefined;
@@ -50,6 +52,7 @@ export declare const SecondOpinionInputSchema: z.ZodObject<{
     includeTypes?: boolean | undefined;
     includeFiles?: string[] | undefined;
     maxTokens?: number | undefined;
+    prNumber?: number | undefined;
     task?: string | undefined;
     sessionName?: string | undefined;
     customPrompt?: string | undefined;
@@ -67,6 +70,11 @@ export interface SecondOpinionDryRunOutput {
     budgetWarnings: BudgetWarning[];
     /** Human-readable message about the dry run status */
     message: string;
+    /** Present when PR detection failed (e.g. gh not installed) */
+    prDetectionFailure?: {
+        reason: string;
+        message: string;
+    };
 }
 export interface SecondOpinionOutput {
     dryRun?: false;
@@ -80,6 +88,11 @@ export interface SecondOpinionOutput {
     filesReviewed: number;
     contextTokens: number;
     summary: EgressSummary;
+    /** Present when PR detection failed (e.g. gh not installed) */
+    prDetectionFailure?: {
+        reason: string;
+        message: string;
+    };
 }
 export declare function executeReview(input: SecondOpinionInput): Promise<SecondOpinionOutput | SecondOpinionDryRunOutput>;
 export { resetRateLimiter } from "../security/rate-limiter.js";

package/dist/tools/review.js

@@ -79,6 +79,11 @@ export const SecondOpinionInputSchema = z.object({
         .number()
         .default(100000)
         .describe("Maximum tokens for context"),
+    // PR options
+    prNumber: z
+        .number()
+        .optional()
+        .describe("PR number to review. Auto-detects from current branch if omitted."),
     // LLM options
     temperature: z
         .number()
@@ -108,36 +113,30 @@ export const SecondOpinionInputSchema = z.object({
  * Build egress summary from bundle, categorizing files as project vs external
  */
 function buildEgressSummary(bundle, projectPath, provider) {
-    const projectFilePaths = [];
-    const externalFilePaths = [];
-    for (const file of bundle.files) {
-        if (isWithinProject(file.path, projectPath)) {
-            projectFilePaths.push(file.path);
-        }
-        else {
-            externalFilePaths.push(file.path);
-        }
-    }
-    // Get unique parent directories of external files
-    const externalLocations = [
-        ...new Set(externalFilePaths.map((p) => path.dirname(p))),
-    ];
+    const projectFilePaths = bundle.files
+        .filter((f) => isWithinProject(f.path, projectPath))
+        .map((f) => f.path);
+    const externalFilePaths = bundle.files
+        .filter((f) => !isWithinProject(f.path, projectPath))
+        .map((f) => f.path);
+    const { redactionStats, prMetadata } = bundle;
     return {
         projectFilesSent: projectFilePaths.length,
         projectFilePaths,
         externalFilesSent: externalFilePaths.length,
         externalFilePaths,
-        externalLocations,
-        blockedFiles: bundle.omittedFiles.map((f) => ({
-            path: f.path,
-            reason: f.reason,
-        })),
+        externalLocations: [...new Set(externalFilePaths.map((p) => path.dirname(p)))],
+        blockedFiles: bundle.omittedFiles.map((f) => ({ path: f.path, reason: f.reason })),
         provider,
-        // Include redaction stats if any secrets were found
-        redactions: bundle.redactionStats.totalCount > 0
+        redactions: redactionStats.totalCount > 0
+            ? { totalCount: redactionStats.totalCount, types: redactionStats.types }
+            : undefined,
+        prContext: prMetadata
             ? {
-                totalCount: bundle.redactionStats.totalCount,
-                types: bundle.redactionStats.types,
+                prNumber: prMetadata.number,
+                prUrl: prMetadata.url,
+                commentsIncluded: prMetadata.commentsCount,
+                reviewsIncluded: prMetadata.reviewsCount,
             }
             : undefined,
     };
@@ -158,6 +157,7 @@ export async function executeReview(input) {
         includeTests: input.includeTests,
         includeTypes: input.includeTypes,
         maxTokens: input.maxTokens,
+        prNumber: input.prNumber,
     });
     // Build egress summary (used for both dry run and actual execution)
     const summary = buildEgressSummary(bundle, input.projectPath, input.provider);
@@ -173,6 +173,7 @@ export async function executeReview(input) {
             message: hasWarnings
                 ? `⚠️ ${bundle.budgetWarnings.length} budget warning(s) - some important files will be omitted`
                 : "Ready to send",
+            prDetectionFailure: bundle.prDetectionFailure,
         };
     }
     // 3. Check rate limit before calling external API
@@ -188,9 +189,7 @@ export async function executeReview(input) {
     const instructions = loadReviewInstructions(input.projectPath);
     // 6. Determine temperature (input > config > default)
     const temperature = input.temperature ?? config.temperature;
-    // 7. Check if files were omitted due to budget (for system prompt calibration)
-    const hasOmittedFiles = bundle.omittedFiles.some((f) => f.reason === "budget_exceeded");
-    // 8. Create provider and execute task
+    // 7. Create provider and execute task
     const provider = createProvider(input.provider, config);
     const response = await provider.review({
         instructions,
@@ -199,12 +198,11 @@ export async function executeReview(input) {
         focusAreas: input.focusAreas,
         customPrompt: input.customPrompt,
         temperature,
-        hasOmittedFiles,
     });
-    // 6. Derive session name if not provided
+    // 9. Derive session name if not provided
     const sessionName = input.sessionName ||
         deriveSessionName(bundle.conversationContext, "code-review");
-    // 7. Write the output files
+    // 10. Write the output files
     const timestamp = new Date().toISOString();
     const metadata = {
         sessionName,
@@ -216,7 +214,7 @@ export async function executeReview(input) {
         task: input.task,
     };
     const reviewFile = writeReview(input.projectPath, config.reviewsDir, metadata, response.review);
-    // 8. Write egress manifest for audit trail
+    // 11. Write egress manifest for audit trail
     const egressManifestFile = writeEgressManifest(input.projectPath, config.reviewsDir, metadata, summary);
     return {
         dryRun: false,
@@ -230,6 +228,7 @@ export async function executeReview(input) {
         filesReviewed: bundle.files.length,
         contextTokens: bundle.totalTokens,
         summary,
+        prDetectionFailure: bundle.prDetectionFailure,
     };
 }
 // Re-export for testing

package/dist/utils/tokens.d.ts

@@ -16,8 +16,9 @@ export declare function estimateTokens(text: string): number;
  */
 export declare const BUDGET_ALLOCATION: {
     readonly explicit: 0.15;
-    readonly session: 0.3;
-    readonly git: 0.1;
+    readonly session: 0.2;
+    readonly pr: 0.15;
+    readonly git: 0.05;
     readonly dependency: 0.15;
     readonly dependent: 0.15;
     readonly test: 0.1;

package/dist/utils/tokens.js

@@ -18,8 +18,9 @@ export function estimateTokens(text) {
  */
 export const BUDGET_ALLOCATION = {
     explicit: 0.15,
-    session: 0.3,
-    git: 0.1,
+    session: 0.2,
+    pr: 0.15,
+    git: 0.05,
     dependency: 0.15,
     dependent: 0.15,
     test: 0.1,
@@ -33,6 +34,7 @@ export const BUDGET_ALLOCATION = {
 export const CATEGORY_PRIORITY_ORDER = [
     "explicit", // User explicitly requested - highest priority
     "session", // Claude worked on these - critical context
+    "pr", // PR changed files
     "git", // Other git changes
     "dependency", // Files imported by modified code
     "dependent", // Files that import modified code

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "second-opinion-mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "MCP server for getting code reviews from Gemini/GPT in Claude Code",
   "keywords": [
     "mcp",

package/templates/second-opinion.md

@@ -5,7 +5,7 @@ You are a code reviewer providing a second opinion on code changes made during a
 ## Your Role
 
 - Review the code changes objectively and thoroughly
-- Identify potential issues, bugs, security vulnerabilities, or improvements
+- Identify potential issues, bugs, security vulnerabilities, and improvements
 - Be constructive and specific in your feedback
 - Consider the conversation context to understand what was requested
 
@@ -18,6 +18,34 @@ You are a code reviewer providing a second opinion on code changes made during a
 5. **Error Handling**: Are errors handled appropriately?
 6. **Edge Cases**: Are edge cases considered?
 
+## Beyond the Diff
+
+Don't just evaluate the code as presented — consider whether the best fix lives somewhere else entirely.
+
+### Think Upstream
+
+Ask: **"What would have to be true for this problem not to exist?"**
+
+Often the complexity you're reviewing is a symptom of a design choice made earlier. For example, if code is littered with null checks, the real issue might be an upstream API that returns `null` instead of a `Result` type. Flag these when you see them.
+
+### Think Downstream
+
+Ask: **"What assumptions does this change bake in, and who inherits them?"**
+
+Changes at boundaries (APIs, shared types, configuration) ripple outward. If a simpler contract, a tighter type, or a collapsed abstraction at this layer would save downstream consumers from defensive code, say so.
+
+### Permission to Be Bold
+
+You have explicit permission to:
+- Suggest breaking changes (with migration paths)
+- Question whether a requirement should exist at all
+- Propose removing code rather than improving it
+
+Label the confidence level of bold suggestions:
+- **Safe** — Low risk, clearly beneficial
+- **Worth Investigating** — Promising but needs validation
+- **Bold** — High-impact but requires careful consideration
+
 ## Output Format
 
 Structure your review as follows:
@@ -28,6 +56,7 @@ Structure your review as follows:
 ### Critical Issues
 Issues that should be fixed before merging (if any):
 - Issue description
+- **Evidence**: Quote the specific code (file:line) that demonstrates this issue
 - Why it matters
 - Suggested fix
 
@@ -40,6 +69,12 @@ Improvements that would be nice to have:
 Things that are unclear or might need clarification:
 - Question about intent or implementation
 
+### Upstream/Downstream Opportunities
+Changes outside the immediate diff that could improve the overall design:
+- **What/Where**: What change, and where in the stack
+- **Why**: How it simplifies or strengthens the current code
+- **Risk Level**: Safe / Worth Investigating / Bold
+
 ### What's Done Well
 Positive aspects of the implementation:
 - Good practices observed
@@ -47,7 +82,7 @@ Positive aspects of the implementation:
 
 ## Guidelines
 
-- Be specific: Reference file names and line numbers when possible
+- Be specific: Reference file names and line numbers. For Critical Issues, quote the relevant code
 - Be constructive: Don't just point out problems, suggest solutions
 - Be proportionate: Don't nitpick minor style issues if there are bigger concerns
 - Consider context: The conversation shows what was asked for - review against those requirements