@cantinasecurity/apex-cli 0.1.2 → 0.1.4

package/.claude/skills/apex-cli/SKILL.md

@@ -19,7 +19,9 @@ Recommended workflow:
 4. Call `apex-doctor` before starting a scan if workspace binding or source planning might be unclear.
 5. If the directory is not bound to the right workspace, call `apex-workspaces` and `apex-workspace-use`.
 6. Use `apex-scan`, `apex-status`, `apex-scans`, `apex-findings`, and `apex-export-findings` for the scan lifecycle.
-7. Use `apex-finding-comment` and `apex-finding-feedback` when the user wants to leave review notes or valid/invalid feedback on a finding.
+7. For PR scans, call `apex-scan` with `mode: "pr"` and `pullRequests`.
+8. Use `apex-finding-comment` and `apex-finding-feedback` when the user wants to leave review notes or valid/invalid feedback on a finding.
+9. When an agent creates a fix PR externally, call `apex-finding-feedback` with `status: "valid"`, `labels: ["fixed"]`, and `fixPrUrls`, then call `apex-finding-fix-review` to start the fix review scan.
 
 If the Apex MCP server is not configured, fall back to the local CLI:
 
@@ -31,16 +33,20 @@ If the Apex MCP server is not configured, fall back to the local CLI:
 - `apex scan` scans the current working directory by default; pass `--repo` only when the user asks to scan explicit alternate roots.
 - `apex-doctor` reports whether Apex will use remote materialization or a local snapshot upload for each selected source.
 - Plain local directories and dirty git worktrees can scan through local snapshot uploads without provider access.
-- Audit scans use `--mode audit` in user-facing CLI calls. The legacy `ultra` mode remains accepted as an alias, but audit scans still require provider-backed GitHub or GitLab sources.
+- Audit scans use `--mode audit` in user-facing CLI calls and request payloads. The legacy `ultra` mode remains accepted as an alias, but audit scans still require provider-backed GitHub or GitLab sources.
+- PR scans use `--mode pr --pr <number>` in CLI calls, or `mode: "pr"` with `pullRequests` in MCP. They require one provider-backed GitHub repository.
 - `apex-workspace-use` accepts a workspace name, prefix, or ID.
 - Use `sourceMode: "remote"` only when the user explicitly wants to forbid local snapshot fallbacks.
-- Finding comments and feedback currently require `CANTINA_AUTH_TOKEN` in the MCP server environment because those writes go through the Cantina web-app routes instead of the Apex CLI bearer-token routes.
+- Finding comments, feedback, and fix review scan starts currently require `CANTINA_AUTH_TOKEN` in the MCP server environment because those writes go through the Cantina web-app routes instead of the Apex CLI bearer-token routes.
 - Invalid finding feedback requires `dismissalReason`; valid feedback can include `suggestedSeverity`, including `extreme`.
+- Fix PR callback feedback requires valid feedback with `labels: ["fixed"]` and `fixPrUrls`; start the fix review scan with `apex-finding-fix-review` after saving that feedback.
 - Finding identifiers such as `KERN2-25` resolve against the selected or latest scan for the current workspace binding. Pass an explicit `scanId` when needed, or use the finding UUID directly.
 
 ## Examples
 
 - Start a scan for the current repository or directory: run `apex-doctor`, bind a workspace if needed, then call `apex-scan`.
+- Start a PR scan: call `apex-scan` with `mode: "pr"` and `pullRequests`.
 - Check an active scan: call `apex-status`, then `apex-findings` when the scan completes.
 - Export findings for review: call `apex-export-findings` with `format` set to `markdown`, `json`, or `gitlab-sast`.
 - Leave review feedback: call `apex-finding-comment` to add a note, or `apex-finding-feedback` with `status` set to `valid` or `invalid`.
+- Add a Fix PR and run fix review: call `apex-finding-feedback` with `status: "valid"`, `labels: ["fixed"]`, and `fixPrUrls`, then call `apex-finding-fix-review`.

package/README.md

@@ -99,11 +99,13 @@ Supported shell commands:
 
 - `/credits`
 - `/scan [standard|audit]`
+- `/scan pr <pr-number>`
 - `/scans`
 - `/findings [scan-id]`
 - `/findings comment <finding-id|finding-identifier> <comment>`
 - `/findings feedback <finding-id|finding-identifier> valid [comment]`
 - `/findings feedback <finding-id|finding-identifier> invalid <false-positive|by-design|not-relevant> [comment]`
+- `/findings fix-review <finding-id|finding-identifier>`
 - `/export [scan-id]`
 - `/workspaces`
 - `/cancel-scan [scan-id]`
@@ -129,10 +131,12 @@ Supported shell commands:
 
 - `apex credits`
 - `apex scan`
+- `apex scan --mode pr --pr <number> [--pr <number>] [--pr-path <path>]`
 - `apex scans`
 - `apex findings [--scan <scan-id>]`
 - `apex findings comment <finding-id|finding-identifier> --content <markdown> [--parent-comment <comment-id>] [--scan <scan-id>]`
-- `apex findings feedback <finding-id|finding-identifier> <valid|invalid> [comment] [--comment <markdown>] [--scan <scan-id>] [--suggested-severity extreme|critical|high|medium|low|informational] [--dismissal-reason false-positive|by-design|not-relevant]`
+- `apex findings feedback <finding-id|finding-identifier> <valid|invalid> [comment] [--comment <markdown>] [--scan <scan-id>] [--suggested-severity extreme|critical|high|medium|low|informational] [--dismissal-reason false-positive|by-design|not-relevant] [--label acknowledged|fixed] [--fix-pr-url <github-pr-url>]`
+- `apex findings fix-review <finding-id|finding-identifier> [--scan <scan-id>]`
 - `apex export findings [--scan <scan-id>] [--format markdown|json|gitlab-sast] [--output <path>]`
 - `apex workspaces`
 - `apex workspace`
@@ -161,16 +165,26 @@ Finding review collaboration now has explicit write commands:
 - `apex findings comment <finding-id|finding-identifier> --content "Needs auth check"`
 - `apex findings feedback <finding-id|finding-identifier> valid --comment "Reproduced on latest build"`
 - `apex findings feedback <finding-id|finding-identifier> invalid --dismissal-reason false-positive --comment "This path is unreachable"`
+- `apex findings feedback <finding-id|finding-identifier> valid --label fixed --fix-pr-url https://github.com/acme/app/pull/123 --comment "Fixed in PR #123"`
+- `apex findings fix-review <finding-id|finding-identifier>`
 - `/findings comment <finding-ref> <comment>`
 - `/findings feedback <finding-ref> valid [comment]`
 - `/findings feedback <finding-ref> invalid <false-positive|by-design|not-relevant> [comment]`
+- `/findings fix-review <finding-ref>`
 
 Identifiers such as `KERN2-25` are resolved against the selected or latest scan for the current workspace binding. Pass `--scan <scan-id>` when you need a specific scan, or pass the finding UUID directly to skip workspace-based resolution.
 
-Finding comments and valid/invalid feedback currently require a Cantina web session token in `CANTINA_AUTH_TOKEN`. Set it to the value of your logged-in `auth_token` cookie before using the write commands or the corresponding MCP tools.
+Finding comments, valid/invalid feedback, and fix review scan starts currently require a Cantina web session token in `CANTINA_AUTH_TOKEN`. Set it to the value of your logged-in `auth_token` cookie before using the write commands or the corresponding MCP tools.
 
 Invalid feedback requires a dismissal reason. Valid feedback can include `--suggested-severity extreme|critical|high|medium|low|informational`.
 
+Fix review scans use a two-step callback flow for agents that create a PR outside Apex:
+
+1. Save fixed feedback on the finding with `--label fixed` and one or more `--fix-pr-url` values.
+2. Start the scan with `apex findings fix-review <finding-id|finding-identifier>`.
+
+The matching MCP flow is `apex-finding-feedback` with `status: "valid"`, `labels: ["fixed"]`, and `fixPrUrls`, followed by `apex-finding-fix-review`.
+
 This is intentionally documented as a separate auth requirement because the current Apex read APIs and finding review write APIs do not accept the same credentials:
 
 - read operations such as `apex findings`, `apex export findings`, and `apex-findings` use the Apex CLI device-login bearer token
@@ -188,11 +202,15 @@ Useful flags:
 
 - `--repo <path>` to scan one or more explicit local roots instead of the current directory
 - `--source-mode auto|remote|local` to control remote-first fallback behavior
-- `--mode standard|audit` to choose the scan mode
+- `--mode standard|audit|pr` to choose the scan mode
+- `--pr <number>` to select one or more GitHub pull requests for `--mode pr`
+- `--pr <number:path,path>` or `--pr-path <path>` to limit a PR scan to changed paths
 
 `auto` is the default. `remote` requires Apex to materialize from a remote repository. `local` forces a local snapshot upload even when a clean remote path is available.
 
-Audit scans still require provider-backed GitHub or GitLab repositories that Apex can materialize remotely without a local snapshot fallback. `ultra` remains accepted as a backwards-compatible alias for the audit scan mode.
+Audit scans use `audit` as the scan mode and still require provider-backed GitHub or GitLab repositories that Apex can materialize remotely without a local snapshot fallback. `ultra` remains accepted as a backwards-compatible alias.
+
+PR scans require exactly one provider-backed GitHub repository. If the current directory resolves to multiple sources, pass `--repo <path>` to select the one that contains the pull request.
 
 ## LLM / MCP Usage
 
@@ -264,7 +282,9 @@ The MCP server exposes Apex-specific tools for:
 - doctor, credits, and provider connection URLs
 - workspace inspection and workspace binding
 - scan start, status, cancellation, findings, and findings export
+- PR scan start by calling `apex-scan` with `mode: "pr"` and `pullRequests`
 - finding comments and valid/invalid feedback with `apex-finding-comment` and `apex-finding-feedback`
+- Fix PR callback and fix review scans with `apex-finding-feedback` plus `apex-finding-fix-review`
 
 For repository-scoped operations, pass `cwd` explicitly so the server can resolve the right `.apex/workspace.json` binding and repository roots.
 

package/dist/apex.js

@@ -1,6 +1,6 @@
 import { ApexApiClient, formatApiError } from "./api-client.js";
 import { parseArgs } from "./args.js";
-import { commandCancelScan, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindingComment, commandFindingFeedback, commandFindings, commandLogin, commandLogout, commandScan, commandScans, commandSetup, commandStatus, commandUpdate, commandWorkspace, commandWorkspaceUse, commandWorkspaces, } from "./commands.js";
+import { commandCancelScan, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindingComment, commandFindingFeedback, commandFindingFixReview, commandFindings, commandLogin, commandLogout, commandScan, commandScans, commandSetup, commandStatus, commandUpdate, commandWorkspace, commandWorkspaceUse, commandWorkspaces, } from "./commands.js";
 import { CLI_HELP_TEXT } from "./help.js";
 import { runMcpServer } from "./mcp.js";
 import { runInteractiveShell } from "./shell.js";
@@ -86,9 +86,16 @@ async function main() {
                     comment: parsed.args.slice(2).join(" ").trim() || getFlagValue(parsed.flags.comment),
                     suggestedSeverity: getFlagValue(parsed.flags["suggested-severity"]),
                     dismissalReason: getFlagValue(parsed.flags["dismissal-reason"]),
+                    labels: getFlagValues(parsed.flags.label),
+                    fixPrUrls: getFlagValues(parsed.flags["fix-pr-url"]),
                 });
                 return;
             }
+            if (parsed.subcommand === "fix-review") {
+                const findingRef = parsed.args[0] ?? "";
+                await commandFindingFixReview(client, cwd, parsed.flags, findingRef);
+                return;
+            }
             await commandFindings(client, cwd, parsed.flags);
             return;
         case "export":
@@ -113,6 +120,14 @@ async function main() {
 function getFlagValue(value) {
     return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
 }
+function getFlagValues(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => item.trim()).filter((item) => item.length > 0);
+    }
+    return typeof value === "string" && value.trim().length > 0
+        ? [value.trim()]
+        : [];
+}
 main().catch((error) => {
     if (error instanceof Error && error.reported) {
         process.exitCode = 1;

package/dist/args.js

@@ -1,4 +1,5 @@
 const BOOLEAN_FLAGS = new Set(["force", "non-interactive", "json", "no-open", "help"]);
+const REPEATABLE_VALUE_FLAGS = new Set(["repo", "pr", "pr-path", "fix-pr-url", "label"]);
 export function parseArgs(argv) {
     const flags = {};
     const positional = [];
@@ -17,7 +18,7 @@ export function parseArgs(argv) {
         if (!next || next.startsWith("--")) {
             throw new Error(`Missing value for --${key}`);
         }
-        if (key === "repo") {
+        if (REPEATABLE_VALUE_FLAGS.has(key)) {
             const existing = flags[key] ?? [];
             existing.push(next);
             flags[key] = existing;

package/dist/commands.js

@@ -1,14 +1,14 @@
-import { getFlagString, isJsonMode, isNonInteractive } from "./args.js";
+import { getFlagList, getFlagString, isJsonMode, isNonInteractive } from "./args.js";
 import { logout } from "./auth.js";
 import { ApiError } from "./api-client.js";
 import { openInBrowser } from "./browser.js";
 import { loadConfig, saveConfig } from "./config.js";
-import { createFindingComment, fetchScanExport, fetchScanFindings, isFindingUuid, normalizeFindingRef, requireCantinaAuthToken, resolveFindingSelection, resolveScanSelection, submitFindingFeedback, } from "./findings.js";
+import { createFindingComment, fetchScanExport, fetchScanFindings, isFindingUuid, normalizeFindingRef, requireCantinaAuthToken, resolveFindingSelection, resolveScanSelection, startFindingFixReviewScan, submitFindingFeedback, } from "./findings.js";
 import { prepareExplicitScanSources, supportsLegacyRemoteFlow, } from "./local-source-scan.js";
 import { logLine, printJson, withLoadingIndicator } from "./output.js";
 import { confirm } from "./prompt.js";
 import { cancelScan, fetchWorkspaceScans, findMostRelevantActiveScan, getScanDisplayLabel, getScanDisplayId, getTrackedScanId, isActiveScanStatus, matchesScanId, selectDefaultScanToCancel, } from "./scan.js";
-import { chooseCompany, createWorkspaceBinding, ensureAuthenticated, resolveWorkspaceSelection, resolveWorkspaceSelectionLegacy, resolveWorkspaceAllowingMissingConnections, selectWorkspaceTarget, } from "./session.js";
+import { chooseCompany, createWorkspaceBinding, ensureAuthenticated, remediateMissingConnections, resolveWorkspaceSelection, resolveWorkspaceSelectionLegacy, resolveWorkspaceAllowingMissingConnections, selectWorkspaceTarget, } from "./session.js";
 import { createWorkspaceBindingFromSummary, fetchCompanyCredits, fetchCompanyWorkspaces, findWorkspaceByRef, } from "./workspaces.js";
 import { loadWorkspaceBinding, saveWorkspaceBinding } from "./workspace-binding.js";
 import { commandSetup as runCliSetup } from "./setup.js";
@@ -31,6 +31,10 @@ const FINDING_DISMISSAL_REASONS = [
     "by-design",
     "not-relevant",
 ];
+const FINDING_FEEDBACK_LABELS = [
+    "acknowledged",
+    "fixed",
+];
 async function saveCompanyDefault(companyId) {
     const config = await loadConfig();
     if (config.defaultCompanyId !== companyId) {
@@ -78,7 +82,192 @@ function formatAuditScanBalance(scanBalance) {
     return `Audit scans: ${detailParts.join(", ")}`;
 }
 function normalizeRequestedScanMode(value) {
-    return value === "ultra" || value === "audit" ? "ultra" : "standard";
+    if (value === "ultra" || value === "audit") {
+        return "audit";
+    }
+    if (value === "pr") {
+        return "pr";
+    }
+    return "standard";
+}
+function getFlagValues(flags, key) {
+    const values = getFlagList(flags, key);
+    const single = getFlagString(flags, key);
+    if (single && values.length === 0) {
+        return [single];
+    }
+    return values;
+}
+function parsePullRequestNumber(value) {
+    const trimmed = value.trim();
+    const direct = Number(trimmed);
+    if (Number.isInteger(direct) && direct > 0) {
+        return direct;
+    }
+    const urlMatch = trimmed.match(/\/pull\/(\d+)(?:\D|$)/i);
+    if (urlMatch?.[1]) {
+        const parsed = Number(urlMatch[1]);
+        return Number.isInteger(parsed) && parsed > 0 ? parsed : null;
+    }
+    return null;
+}
+function normalizeRepositoryUrl(value) {
+    return value.replace(/\.git$/i, "").replace(/\/+$/, "").toLowerCase();
+}
+function parseGithubPullRequestUrl(value) {
+    const withPathFilter = value.match(/^(https?:\/\/github\.com\/[^/\s]+\/[^/\s]+\/pull\/\d+):(.+)$/i);
+    const urlValue = withPathFilter?.[1] ?? value;
+    const match = urlValue.match(/^https?:\/\/github\.com\/([^/\s]+)\/([^/\s]+)\/pull\/(\d+)(?:[/?#].*)?$/i);
+    if (!match?.[1] || !match[2] || !match[3]) {
+        return null;
+    }
+    const number = parsePullRequestNumber(match[3]);
+    if (!number) {
+        return null;
+    }
+    return {
+        number,
+        repoUrl: `https://github.com/${match[1]}/${match[2]}.git`,
+        pathFilterValue: withPathFilter?.[2] ?? null,
+    };
+}
+function parsePrScanPullRequestSelection(value) {
+    const trimmed = value.trim();
+    const numericWithPaths = trimmed.match(/^(\d+)(?::(.+))?$/);
+    const githubUrl = numericWithPaths ? null : parseGithubPullRequestUrl(trimmed);
+    const pathFilterValue = numericWithPaths?.[2] ?? githubUrl?.pathFilterValue ?? null;
+    const number = parsePullRequestNumber(numericWithPaths?.[1] ?? (githubUrl ? String(githubUrl.number) : trimmed));
+    if (!number) {
+        throw new Error(`Invalid pull request selection "${value}". Use --pr <number> or --pr <number:path,path>.`);
+    }
+    const paths = pathFilterValue
+        ?.split(",")
+        .map((pathValue) => pathValue.trim().replace(/^\/+/, ""))
+        .filter((pathValue) => pathValue.length > 0) ?? [];
+    return { number, paths, repoUrl: githubUrl?.repoUrl ?? null };
+}
+function parsePrScanPullRequestSelections(flags) {
+    const prValues = getFlagValues(flags, "pr").flatMap((value) => {
+        const trimmed = value.trim();
+        if (/^\d+(,\d+)+$/.test(trimmed)) {
+            return trimmed.split(",");
+        }
+        return [trimmed];
+    });
+    const pathValues = getFlagValues(flags, "pr-path")
+        .map((value) => value.trim().replace(/^\/+/, ""))
+        .filter((value) => value.length > 0);
+    if (prValues.length === 0) {
+        if (pathValues.length > 0) {
+            throw new Error("--pr-path requires a --pr selection.");
+        }
+        return [];
+    }
+    const selections = prValues.map(parsePrScanPullRequestSelection);
+    if (pathValues.length > 0) {
+        if (selections.length !== 1) {
+            throw new Error("--pr-path can only be used with a single --pr selection. Use --pr <number:path,path> for per-PR path selection.");
+        }
+        selections[0] = {
+            ...selections[0],
+            paths: Array.from(new Set([...selections[0].paths, ...pathValues])),
+        };
+    }
+    const seen = new Map();
+    for (const selection of selections) {
+        const existing = seen.get(selection.number);
+        if (existing?.repoUrl &&
+            selection.repoUrl &&
+            normalizeRepositoryUrl(existing.repoUrl) !==
+                normalizeRepositoryUrl(selection.repoUrl)) {
+            throw new Error(`PR #${selection.number} was selected from multiple repositories. Use PR selections from one repository at a time.`);
+        }
+        const paths = existing && (existing.paths.length === 0 || selection.paths.length === 0)
+            ? []
+            : Array.from(new Set([...(existing?.paths ?? []), ...selection.paths])).sort((left, right) => left.localeCompare(right));
+        seen.set(selection.number, {
+            number: selection.number,
+            paths,
+            repoUrl: existing?.repoUrl ?? selection.repoUrl,
+        });
+    }
+    return [...seen.values()];
+}
+function resolvePrScanSource(repositories) {
+    if (repositories.length === 0) {
+        throw new Error("PR scans require a provider-backed GitHub repository.");
+    }
+    if (repositories.length > 1) {
+        throw new Error("PR scans require exactly one GitHub repository. Re-run with --repo to select a single source root.");
+    }
+    const source = repositories[0];
+    if (source.provider !== "github") {
+        throw new Error("PR scans require a provider-backed GitHub repository.");
+    }
+    if (typeof source.installationId !== "number") {
+        throw new Error("PR scans require GitHub App installation access for the selected repository.");
+    }
+    return source;
+}
+function ensurePrSelectionsMatchSource(selections, source) {
+    const expectedRepoUrl = normalizeRepositoryUrl(source.repoUrl);
+    const mismatched = selections.find((selection) => selection.repoUrl &&
+        normalizeRepositoryUrl(selection.repoUrl) !== expectedRepoUrl);
+    if (mismatched?.repoUrl) {
+        throw new Error(`PR #${mismatched.number} references ${mismatched.repoUrl}, but the selected repository is ${source.repoUrl}. Re-run with --repo for that repository or pass a PR number for the selected repository.`);
+    }
+}
+function formatMissingProviderConnections(missing) {
+    return missing
+        .map((item) => `${item.provider} ${item.repoUrl}`)
+        .join(", ");
+}
+function buildPrScanRepositoriesPayload(params) {
+    return [
+        {
+            provider: "github",
+            repoUrl: params.source.repoUrl,
+            installationId: params.source.installationId,
+            sourceType: "pr",
+            pullRequests: params.pullRequests.map((pullRequest) => ({
+                number: pullRequest.number,
+                ...(pullRequest.paths.length > 0 ? { paths: pullRequest.paths } : {}),
+            })),
+        },
+    ];
+}
+function getPrScanSourceDisplayName(source) {
+    const normalizedUrl = source.repoUrl.replace(/\.git$/i, "");
+    const repoMatch = normalizedUrl.match(/github\.com[:/]([^/]+\/[^/]+)$/i);
+    if (repoMatch?.[1]) {
+        return repoMatch[1];
+    }
+    return source.path && source.path !== "."
+        ? source.path
+        : path.posix.basename(normalizedUrl);
+}
+function buildPrScanPlannedSource(source) {
+    return {
+        path: source.path || ".",
+        displayName: getPrScanSourceDisplayName(source),
+        relativePath: source.path || ".",
+        sourceKind: "remote_repo",
+        provider: "github",
+        repoUrl: source.repoUrl,
+        ref: {
+            type: "default",
+            value: "default",
+        },
+        installationId: source.installationId,
+        connectionId: source.connectionId ?? null,
+        projectId: source.projectId ?? null,
+        baseUrl: source.baseUrl ?? null,
+        materializationAuth: "installation",
+    };
+}
+function getPrScanSelectedSources(sources, source) {
+    const matchedSources = sources.filter((candidate) => candidate.kind === "git_candidate" && candidate.repoUrl === source.repoUrl);
+    return matchedSources.length > 0 ? matchedSources : sources;
 }
 function normalizeFindingRefInput(value) {
     const trimmed = normalizeFindingRef(value);
@@ -97,6 +286,22 @@ function normalizeFeedbackSeverity(value) {
     }
     throw new Error(`Suggested severity must be one of: ${FINDING_FEEDBACK_SEVERITIES.join(", ")}.`);
 }
+function normalizeFeedbackLabels(values) {
+    const normalized = Array.from(new Set((values ?? [])
+        .map((value) => value.trim())
+        .filter((value) => value.length > 0)));
+    if (normalized.length === 0) {
+        return null;
+    }
+    const invalid = normalized.find((value) => !FINDING_FEEDBACK_LABELS.includes(value));
+    if (invalid) {
+        throw new Error(`Feedback label must be one of: ${FINDING_FEEDBACK_LABELS.join(", ")}.`);
+    }
+    if (normalized.length > 1) {
+        throw new Error("Select at most one feedback label.");
+    }
+    return normalized;
+}
 function normalizeDismissalReason(value) {
     const normalized = value?.trim() ?? "";
     if (!normalized) {
@@ -341,10 +546,17 @@ export async function commandConnect(client, cwd, flags, provider) {
     return { provider, company, url: response.url };
 }
 export async function commandScan(client, cwd, flags) {
+    const requestedMode = normalizeRequestedScanMode(getFlagString(flags, "mode"));
+    const prSelections = parsePrScanPullRequestSelections(flags);
+    if (requestedMode !== "pr" && prSelections.length > 0) {
+        throw new Error("Pull request selections require --mode pr.");
+    }
+    if (requestedMode === "pr" && prSelections.length === 0) {
+        throw new Error("PR scans require at least one --pr <number> selection.");
+    }
     const me = await ensureAuthenticated(client, flags);
     const selection = await selectWorkspaceTarget(cwd, me, flags);
     const result = await withLoadingIndicator("Resolving workspace and scan plan...", flags, () => resolveWorkspaceSelection(client, selection));
-    const requestedMode = normalizeRequestedScanMode(getFlagString(flags, "mode"));
     if (!result.resolve.workspaceId) {
         throw new Error("Workspace resolution did not return a workspaceId.");
     }
@@ -353,7 +565,43 @@ export async function commandScan(client, cwd, flags) {
     const forceRestart = await ensureScanRestartConfirmed(flags, activeScan);
     let workspaceId = resolvedWorkspaceId;
     let scan;
-    if (requestedMode === "ultra") {
+    let prScanSource = null;
+    if (requestedMode === "pr") {
+        let legacyResolve = await withLoadingIndicator("Preparing PR scan...", flags, () => resolveWorkspaceSelectionLegacy(client, selection, resolvedWorkspaceId));
+        if (!legacyResolve.workspaceId) {
+            throw new Error("Workspace resolution did not return a workspaceId.");
+        }
+        if (legacyResolve.missing.length > 0) {
+            if (isNonInteractive(flags)) {
+                throw new Error(`PR scans require connected provider access for ${formatMissingProviderConnections(legacyResolve.missing)}. Re-run interactively or pre-connect providers.`);
+            }
+            await remediateMissingConnections(legacyResolve.missing, flags);
+            legacyResolve = await withLoadingIndicator("Rechecking PR scan sources...", flags, () => resolveWorkspaceSelectionLegacy(client, selection, legacyResolve.workspaceId));
+            if (!legacyResolve.workspaceId) {
+                throw new Error("Workspace resolution did not return a workspaceId.");
+            }
+            if (legacyResolve.missing.length > 0) {
+                throw new Error(`PR scans require connected provider access for ${formatMissingProviderConnections(legacyResolve.missing)}.`);
+            }
+        }
+        workspaceId = legacyResolve.workspaceId;
+        const prSource = resolvePrScanSource(legacyResolve.repositories);
+        ensurePrSelectionsMatchSource(prSelections, prSource);
+        prScanSource = prSource;
+        scan = await withLoadingIndicator("Starting PR scan...", flags, () => client.request(`/api/cli/v1/local-workspaces/${encodeURIComponent(workspaceId)}/scan`, {
+            method: "POST",
+            json: {
+                mode: "pr",
+                scanType: "pr",
+                force: forceRestart || flags.force === true,
+                repositories: buildPrScanRepositoriesPayload({
+                    source: prSource,
+                    pullRequests: prSelections,
+                }),
+            },
+        }));
+    }
+    else if (requestedMode === "audit") {
         if (!supportsLegacyRemoteFlow(result.resolve.plannedSources)) {
             throw new Error("Audit scans currently require provider-backed GitHub or GitLab repositories without local snapshot fallbacks.");
         }
@@ -396,13 +644,19 @@ export async function commandScan(client, cwd, flags) {
     };
     await saveWorkspaceBinding(cwd, binding);
     await saveCompanyDefault(result.company.id);
-    const localSnapshotCount = result.resolve.plannedSources.filter((source) => source.sourceKind === "local_archive").length;
+    const summarySources = prScanSource
+        ? getPrScanSelectedSources(result.sources, prScanSource)
+        : result.sources;
+    const summaryPlannedSources = prScanSource
+        ? [buildPrScanPlannedSource(prScanSource)]
+        : result.resolve.plannedSources;
+    const localSnapshotCount = summaryPlannedSources.filter((source) => source.sourceKind === "local_archive").length;
     const payload = {
         company: result.company,
         workspaceId,
         workspaceName: result.workspaceName,
-        sources: result.sources,
-        plannedSources: result.resolve.plannedSources,
+        sources: summarySources,
+        plannedSources: summaryPlannedSources,
         scan: {
             ...scan,
             apexScanId: scan.apexScanId ?? scan.bedrockScanId ?? null,
@@ -416,12 +670,15 @@ export async function commandScan(client, cwd, flags) {
     logLine(`Authenticated as ${me.user.username ?? me.user.id}`, flags);
     logLine(`Company: ${result.company.handle ?? result.company.id}`, flags);
     logLine(`Workspace: ${result.workspaceName}`, flags);
-    logLine(`Sources selected: ${result.sources.length}`, flags);
-    logLine(`Plan: ${result.resolve.plannedSources.length - localSnapshotCount} remote, ${localSnapshotCount} local snapshot`, flags);
+    logLine(`Sources selected: ${summarySources.length}`, flags);
+    logLine(`Plan: ${summaryPlannedSources.length - localSnapshotCount} remote, ${localSnapshotCount} local snapshot`, flags);
     logLine(`Scan: ${scan.status}${getTrackedScanId(scan) ? ` (${getTrackedScanId(scan)})` : ""}`, flags);
     if (scan.scanUrl) {
         logLine(`View: ${scan.scanUrl}`, flags);
     }
+    if (scan.fullScanRecommendation) {
+        logLine(`Recommendation: ${scan.fullScanRecommendation}`, flags);
+    }
     logLine("Next: run `apex status` to watch progress, then `apex findings` when the scan finishes.", flags);
     return payload;
 }
@@ -713,6 +970,14 @@ export async function commandFindingFeedback(client, cwd, flags, params) {
     const findingRef = normalizeFindingRefInput(params.requestedFindingRef);
     const suggestedSeverity = normalizeFeedbackSeverity(params.suggestedSeverity);
     const dismissalReason = normalizeDismissalReason(params.dismissalReason);
+    const fixPrUrls = params.fixPrUrls
+        ?.map((url) => url.trim())
+        .filter((url) => url.length > 0) ?? [];
+    const labels = params.feedbackType === "valid" &&
+        fixPrUrls.length > 0 &&
+        (!params.labels || params.labels.length === 0)
+        ? ["fixed"]
+        : normalizeFeedbackLabels(params.labels);
     if (params.feedbackType === "valid" &&
         dismissalReason) {
         throw new Error("Dismissal reasons are only valid for invalid feedback.");
@@ -724,6 +989,15 @@ export async function commandFindingFeedback(client, cwd, flags, params) {
     if (params.feedbackType === "invalid" && !dismissalReason) {
         throw new Error("Invalid feedback requires a dismissal reason.");
     }
+    if (params.feedbackType !== "valid" && labels?.length) {
+        throw new Error("Feedback labels require valid feedback.");
+    }
+    if (params.feedbackType !== "valid" && fixPrUrls.length > 0) {
+        throw new Error("Fix PR URLs require valid feedback.");
+    }
+    if (fixPrUrls.length > 0 && labels?.[0] !== "fixed") {
+        throw new Error("Fix PR URLs require the fixed feedback label.");
+    }
     requireCantinaAuthToken();
     const currentBinding = await loadWorkspaceBinding(cwd);
     const needsWorkspaceResolution = !isFindingUuid(findingRef);
@@ -744,6 +1018,8 @@ export async function commandFindingFeedback(client, cwd, flags, params) {
         comment: params.comment?.trim() || null,
         suggestedSeverity,
         dismissalReason,
+        labels,
+        fixPrUrls,
     }));
     const nextBinding = await maybePersistFindingSelectionBinding({
         cwd,
@@ -771,11 +1047,78 @@ export async function commandFindingFeedback(client, cwd, flags, params) {
     if (response.feedback.dismissalReason) {
         logLine(`Dismissal reason: ${response.feedback.dismissalReason}`, flags);
     }
+    if (response.feedback.labels?.length) {
+        logLine(`Labels: ${response.feedback.labels.join(", ")}`, flags);
+    }
+    if (response.feedback.fixPrUrls?.length) {
+        logLine(`Fix PRs: ${response.feedback.fixPrUrls.join(", ")}`, flags);
+    }
+    else if (response.feedback.fixPrUrl) {
+        logLine(`Fix PR: ${response.feedback.fixPrUrl}`, flags);
+    }
     if (response.feedback.comment) {
         logLine("Comment: saved", flags);
     }
     return payload;
 }
+export async function commandFindingFixReview(client, cwd, flags, requestedFindingRef) {
+    const findingRef = normalizeFindingRefInput(requestedFindingRef);
+    requireCantinaAuthToken();
+    const currentBinding = await loadWorkspaceBinding(cwd);
+    const needsWorkspaceResolution = !isFindingUuid(findingRef);
+    const binding = needsWorkspaceResolution
+        ? requireLoadedWorkspaceBinding(currentBinding)
+        : currentBinding;
+    if (needsWorkspaceResolution) {
+        await ensureAuthenticated(client, flags);
+    }
+    const selection = await withLoadingIndicator("Resolving finding...", flags, () => resolveFindingSelection({
+        client,
+        binding,
+        requestedFindingRef: findingRef,
+        requestedScanId: getFlagString(flags, "scan"),
+    }));
+    const response = await withLoadingIndicator("Starting fix review scan...", flags, () => startFindingFixReviewScan(client, selection.findingId));
+    const nextBinding = binding && selection.scan
+        ? {
+            ...binding,
+            lastScanId: response.fixReview.scanId,
+            lastScanUrl: null,
+            lastSyncedAt: new Date().toISOString(),
+        }
+        : binding;
+    if (binding && selection.scan && nextBinding) {
+        await saveWorkspaceBinding(cwd, nextBinding);
+    }
+    const payload = {
+        binding: nextBinding,
+        scan: selection.scan,
+        findingId: selection.findingId,
+        findingRef: selection.findingRef,
+        finding: selection.finding,
+        fixReview: response.fixReview,
+        reused: response.reused,
+    };
+    if (isJsonMode(flags)) {
+        printJson(payload);
+        return payload;
+    }
+    logLine(`Finding: ${selection.finding?.findingIdentifier ?? selection.findingId}`, flags);
+    logLine(`Fix review scan: ${response.fixReview.status} (${response.fixReview.scanId})`, flags);
+    if (response.fixReview.kernelScanId) {
+        logLine(`Kernel scan: ${response.fixReview.kernelScanId}`, flags);
+    }
+    if (response.fixReview.fixPrUrls?.length) {
+        logLine(`Fix PRs: ${response.fixReview.fixPrUrls.join(", ")}`, flags);
+    }
+    else {
+        logLine(`Fix PR: ${response.fixReview.fixPrUrl}`, flags);
+    }
+    if (response.reused) {
+        logLine("Reused existing active fix review scan.", flags);
+    }
+    return payload;
+}
 export async function commandExportFindings(client, cwd, flags) {
     await ensureAuthenticated(client, flags);
     const binding = await requireWorkspaceBinding(cwd);

package/dist/findings.js

@@ -2,7 +2,7 @@ import { fetchWorkspaceScans, getScanDisplayId, matchesScanId, } from "./scan.js
 import { ApiError } from "./api-client.js";
 const FINDING_UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const CANTINA_AUTH_TOKEN_ENV = "CANTINA_AUTH_TOKEN";
-const CANTINA_AUTH_TOKEN_ERROR = "Finding comments and feedback currently require `CANTINA_AUTH_TOKEN` from a logged-in Cantina/Apex browser session. Export `CANTINA_AUTH_TOKEN` and retry.";
+const CANTINA_AUTH_TOKEN_ERROR = "Finding comments, feedback, and fix review scans currently require `CANTINA_AUTH_TOKEN` from a logged-in Cantina/Apex browser session. Export `CANTINA_AUTH_TOKEN` and retry.";
 function parsePositiveInt(value) {
     if (!value)
         return null;
@@ -168,10 +168,19 @@ export async function createFindingComment(client, findingId, input) {
     });
 }
 export async function submitFindingFeedback(client, findingId, input) {
+    const fixPrUrls = input.fixPrUrls
+        ?.map((url) => url.trim())
+        .filter((url) => url.length > 0) ?? [];
     return requestFindingAppRoute(client, `/api/findings/${encodeURIComponent(findingId)}/feedback`, {
         method: "POST",
         json: {
             status: input.feedbackType,
+            ...(input.labels && input.labels.length > 0
+                ? { labels: input.labels }
+                : {}),
+            ...(fixPrUrls.length > 0
+                ? { fixPrUrl: fixPrUrls[0], fixPrUrls }
+                : {}),
             ...(input.comment ? { comment: input.comment } : {}),
             ...(input.suggestedSeverity
                 ? { suggestedSeverity: input.suggestedSeverity }
@@ -180,3 +189,9 @@ export async function submitFindingFeedback(client, findingId, input) {
         },
     });
 }
+export async function startFindingFixReviewScan(client, findingId) {
+    return requestFindingAppRoute(client, `/api/findings/${encodeURIComponent(findingId)}/fix-review`, {
+        method: "POST",
+        json: {},
+    });
+}

package/dist/help.js

@@ -8,6 +8,8 @@ export const CLI_HELP_TEXT = `Usage:
                                     Add a comment or note to a finding
   apex findings feedback <finding-id|finding-identifier> <valid|invalid>
                                     Leave feedback; invalid requires --dismissal-reason
+  apex findings fix-review <finding-id|finding-identifier>
+                                    Start a fix review scan after fixed feedback has a Fix PR URL
   apex export findings              Export findings for the latest or selected scan
   apex workspaces                   List accessible workspaces for the active company
   apex workspace                    Show the workspace currently bound to this directory
@@ -36,11 +38,15 @@ Flags:
                                     Attach a suggested severity to valid feedback
   --dismissal-reason false-positive|by-design|not-relevant
                                     Explain why invalid feedback is being left
+  --label acknowledged|fixed        Attach a valid-feedback label
+  --fix-pr-url <github-pr-url>      Attach one or more Fix PR URLs to fixed feedback
   --format markdown|json|gitlab-sast
                                     Choose the export format for findings
   --output <path>                   Write exported findings to this file path
   --limit <count>                   Limit the number of findings returned
-  --mode standard|audit             Choose the scan mode
+  --mode standard|audit|pr          Choose the scan mode
+  --pr <number[:path,path]>         Select a GitHub pull request for --mode pr
+  --pr-path <path>                  Limit a single-PR scan to a changed file path
   --source-mode auto|remote|local   Control remote-vs-local source materialization
   --force                           Start a new scan even if another scan is active
   --repo <path>                     Include one or more explicit local source roots
@@ -52,10 +58,12 @@ Flags:
 Tips:
   apex scan uses the current directory name as the default workspace name unless you pass --workspace-name.
   apex scan uses the current directory as the default source root unless you pass --repo.
-  audit is the user-facing name for the legacy ultra scan mode; ultra remains accepted as an alias.
+  PR scans require --mode pr and at least one --pr selection for a GitHub repository.
+  audit is the current scan mode for audit scans; ultra remains accepted as a legacy alias.
   apex workspace use accepts a workspace name, prefix, or ID.
-  Finding comments and feedback currently require CANTINA_AUTH_TOKEN from a logged-in Cantina/Apex browser session.
+  Finding comments, feedback, and fix review scans currently require CANTINA_AUTH_TOKEN from a logged-in Cantina/Apex browser session.
   Invalid finding feedback requires --dismissal-reason.
+  Fix review scans require valid feedback with --label fixed and at least one --fix-pr-url, then apex findings fix-review.
   Finding identifiers such as KERN2-25 resolve against the selected scan; pass --scan or use the finding UUID directly when needed.
   Quote workspace names that contain spaces:
     apex workspace use "Core Platform"
@@ -65,6 +73,7 @@ export const SHELL_HELP_TEXT = `Press Tab to autocomplete commands and common ar
 Commands:
   /credits                Show scan credits and audit scan entitlements for the active company
   /scan [standard|audit]  Start a new Apex scan for this workspace
+  /scan pr <pr-number>    Start a PR scan for this workspace
   /scans                  List scans for this workspace
   /findings [scan-id]     List findings for the latest or selected scan
   /findings comment <finding-ref> <comment>
@@ -73,6 +82,8 @@ Commands:
                           Leave valid feedback on a finding
   /findings feedback <finding-ref> invalid <reason> [comment]
                           Leave invalid feedback; reason is false-positive, by-design, or not-relevant
+  /findings fix-review <finding-ref>
+                          Start a fix review scan after fixed feedback has a Fix PR URL
   /export [scan-id]       Export findings for the latest or selected scan
   /workspaces             List accessible workspaces for the active company
   /cancel-scan [scan-id]  Cancel a running or most recent scan
@@ -93,10 +104,12 @@ Commands:
   /exit                   Exit Apex
 
 Tips:
-  audit is the user-facing name for the legacy ultra scan mode; ultra remains accepted as an alias.
+  PR scans require a GitHub PR number and provider-backed repository access.
+  audit is the current scan mode for audit scans; ultra remains accepted as a legacy alias.
   /workspace use accepts a workspace name, prefix, or ID.
-  /findings comment and /findings feedback require CANTINA_AUTH_TOKEN in the shell environment.
+  /findings comment, /findings feedback, and /findings fix-review require CANTINA_AUTH_TOKEN in the shell environment.
   Invalid finding feedback requires a dismissal reason.
+  Fix review scans require fixed valid feedback with a Fix PR URL. Use scripted CLI or MCP for attaching Fix PR URLs.
   Use scripted CLI flags for advanced feedback options such as suggested severity or dismissal reason.
   Quote workspace names that contain spaces: /workspace use "Core Platform"
 `;

package/dist/mcp.js

@@ -4,7 +4,7 @@ import path from "node:path";
 import { z } from "zod";
 import { getMe, logout, startDeviceLogin, waitForDeviceLoginApproval } from "./auth.js";
 import { ApexApiClient, formatApiError } from "./api-client.js";
-import { commandCancelScan, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindingComment, commandFindingFeedback, commandFindings, commandScan, commandScans, commandStatus, commandWorkspace, commandWorkspaceUse, commandWorkspaces, } from "./commands.js";
+import { commandCancelScan, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindingComment, commandFindingFeedback, commandFindingFixReview, commandFindings, commandScan, commandScans, commandStatus, commandWorkspace, commandWorkspaceUse, commandWorkspaces, } from "./commands.js";
 import { CLI_HELP_TEXT } from "./help.js";
 import { APEX_CLI_VERSION } from "./version.js";
 const MCP_WORKFLOW_GUIDE = `Use Apex through these tools instead of shelling out to the CLI.
@@ -15,15 +15,18 @@ Suggested workflow:
 3. Call apex-doctor for the target repository cwd.
 4. If the directory is not bound to the right workspace, call apex-workspaces and apex-workspace-use.
 5. Start and monitor scans with apex-scan, apex-status, apex-scans, apex-findings, and apex-export-findings.
-6. Leave finding comments or valid/invalid feedback with apex-finding-comment and apex-finding-feedback when review collaboration is needed.
+6. For PR scans, call apex-scan with mode "pr" and one or more pullRequests.
+7. Leave finding comments or valid/invalid feedback with apex-finding-comment and apex-finding-feedback when review collaboration is needed.
+8. To attach a fix PR and trigger a fix review scan, call apex-finding-feedback with status "valid", label "fixed", and fixPrUrls, then call apex-finding-fix-review.
 
 Notes:
 - Pass cwd explicitly for repository-specific operations.
 - Tool calls are always non-interactive and never auto-open a browser.
-- Use mode "audit" for audit scans; "ultra" remains accepted as a legacy alias.
+- Use mode "audit" for audit scans; "ultra" remains accepted as a legacy alias. Use mode "pr" for GitHub pull request scans.
 - Doctor reports whether Apex will use remote materialization or a local snapshot upload for each source.`;
 const WORKSPACE_BINDING_ERROR = "This directory is not bound to an Apex workspace yet. Run `apex workspaces` to list workspace names, prefixes, and IDs, then bind one with `apex workspace use \"<workspace name>\"`, or run `apex scan` to create or resolve one automatically.";
 const MISSING_PROVIDER_CONNECTIONS_ERROR = "Missing provider connections. Re-run interactively or pre-connect providers.";
+const PR_MISSING_PROVIDER_CONNECTIONS_ERROR_PREFIX = "PR scans require connected provider access for ";
 const MULTIPLE_ACTIVE_SCANS_ERROR = "Multiple active scans are running. Run `apex scans` to list scan IDs, then re-run `apex cancel-scan <scan-id>`.";
 const DUPLICATE_SCAN_FORCE_GUIDANCE = "Re-run with --force to start another scan.";
 const MULTIPLE_COMPANIES_ERROR = "Multiple companies available. Re-run with --company <id-or-handle>.";
@@ -50,9 +53,15 @@ function buildFlags(options) {
     if (options.output) {
         flags.output = options.output;
     }
+    if (options.pullRequests && options.pullRequests.length === 0) {
+        throw new Error("PR scans require at least one pull request.");
+    }
     if (options.mode) {
         flags.mode = options.mode;
     }
+    else if (options.pullRequests) {
+        flags.mode = "pr";
+    }
     if (options.sourceMode) {
         flags["source-mode"] = options.sourceMode;
     }
@@ -62,6 +71,16 @@ function buildFlags(options) {
     if (options.repoPaths && options.repoPaths.length > 0) {
         flags.repo = options.repoPaths;
     }
+    if (options.pullRequests && options.pullRequests.length > 0) {
+        flags.pr = options.pullRequests.map((pullRequest) => {
+            const paths = pullRequest.paths
+                ?.map((pathValue) => pathValue.trim())
+                .filter((pathValue) => pathValue.length > 0) ?? [];
+            return paths.length > 0
+                ? `${pullRequest.number}:${paths.join(",")}`
+                : String(pullRequest.number);
+        });
+    }
     if (typeof options.limit === "number") {
         flags.limit = String(options.limit);
     }
@@ -86,7 +105,8 @@ function formatMcpErrorMessage(toolName, error) {
     if (message === WORKSPACE_BINDING_ERROR) {
         return "No workspace is bound to this directory. Call `apex-workspace-use` to bind an existing workspace, or call `apex-scan` to create or resolve one first.";
     }
-    if (message === MISSING_PROVIDER_CONNECTIONS_ERROR) {
+    if (message === MISSING_PROVIDER_CONNECTIONS_ERROR ||
+        message.startsWith(PR_MISSING_PROVIDER_CONNECTIONS_ERROR_PREFIX)) {
         return "Missing provider connections. Call `apex-connect-provider` for each missing provider, complete the browser flow, then retry `apex-scan`.";
     }
     if (message === MULTIPLE_COMPANIES_ERROR) {
@@ -322,17 +342,25 @@ function registerTools(server) {
     }, (value) => `Bound ${String(value.cwd)} to an Apex workspace.`));
     server.registerTool("apex-scan", {
         title: "Start Apex Scan",
-        description: "Start a new Apex scan for the provided cwd by default. Pass repoPaths only to scan explicit alternate local roots. Use mode audit for audit scans.",
+        description: "Start a new Apex scan for the provided cwd by default. Pass repoPaths only to scan explicit alternate local roots. Use mode audit for audit scans and mode pr for GitHub pull request scans.",
         inputSchema: {
             cwd: z.string().optional(),
             company: z.string().optional(),
             workspaceName: z.string().optional(),
             repoPaths: z.array(z.string()).optional(),
-            mode: z.enum(["standard", "audit", "ultra"]).optional(),
+            mode: z.enum(["standard", "audit", "ultra", "pr"]).optional(),
+            pullRequests: z
+                .array(z.object({
+                number: z.number().int().positive(),
+                paths: z.array(z.string().min(1)).optional(),
+            }))
+                .min(1)
+                .max(20)
+                .optional(),
             sourceMode: z.enum(["auto", "remote", "local"]).optional(),
             force: z.boolean().optional(),
         },
-    }, async ({ cwd, company, workspaceName, repoPaths, mode, sourceMode, force }) => runTool("apex-scan", async () => {
+    }, async ({ cwd, company, workspaceName, repoPaths, mode, pullRequests, sourceMode, force, }) => runTool("apex-scan", async () => {
         const client = new ApexApiClient();
         await requireAuthenticated(client);
         const targetCwd = resolveCwd(cwd);
@@ -341,6 +369,7 @@ function registerTools(server) {
             workspaceName,
             repoPaths,
             mode,
+            pullRequests,
             sourceMode,
             force,
         }));
@@ -442,12 +471,14 @@ function registerTools(server) {
     }, (value) => `Added a finding comment for ${String(value.findingRef)}.`));
     server.registerTool("apex-finding-feedback", {
         title: "Leave Apex Finding Feedback",
-        description: "Leave valid or invalid feedback on an Apex finding. Requires CANTINA_AUTH_TOKEN in the MCP server environment.",
+        description: "Leave valid or invalid feedback on an Apex finding. To attach a fix PR, send status valid with label fixed and fixPrUrls. Requires CANTINA_AUTH_TOKEN in the MCP server environment.",
         inputSchema: {
             cwd: z.string().optional(),
             findingRef: z.string(),
             status: z.enum(["valid", "invalid"]),
             comment: z.string().optional(),
+            labels: z.enum(["acknowledged", "fixed"]).array().max(1).optional(),
+            fixPrUrls: z.array(z.string().url()).max(20).optional(),
             suggestedSeverity: z
                 .enum(["extreme", "critical", "high", "medium", "low", "informational"])
                 .optional(),
@@ -456,7 +487,7 @@ function registerTools(server) {
                 .optional(),
             scanId: z.string().optional(),
         },
-    }, async ({ cwd, findingRef, status, comment, suggestedSeverity, dismissalReason, scanId, }) => runTool("apex-finding-feedback", async () => {
+    }, async ({ cwd, findingRef, status, comment, labels, fixPrUrls, suggestedSeverity, dismissalReason, scanId, }) => runTool("apex-finding-feedback", async () => {
         const client = new ApexApiClient();
         const targetCwd = resolveCwd(cwd);
         const payload = await commandFindingFeedback(client, targetCwd, buildFlags({
@@ -465,6 +496,8 @@ function registerTools(server) {
             requestedFindingRef: findingRef,
             feedbackType: status,
             comment,
+            labels,
+            fixPrUrls,
             suggestedSeverity,
             dismissalReason,
         });
@@ -474,6 +507,25 @@ function registerTools(server) {
         };
     }, (value) => `Submitted ${String((value.feedback?.feedbackType ??
         "finding"))} feedback for ${String(value.findingRef)}.`));
+    server.registerTool("apex-finding-fix-review", {
+        title: "Start Apex Finding Fix Review Scan",
+        description: "Start a fix review scan for a finding after fixed feedback with one or more Fix PR URLs has been saved. Requires CANTINA_AUTH_TOKEN in the MCP server environment.",
+        inputSchema: {
+            cwd: z.string().optional(),
+            findingRef: z.string(),
+            scanId: z.string().optional(),
+        },
+    }, async ({ cwd, findingRef, scanId }) => runTool("apex-finding-fix-review", async () => {
+        const client = new ApexApiClient();
+        const targetCwd = resolveCwd(cwd);
+        const payload = await commandFindingFixReview(client, targetCwd, buildFlags({
+            scanId,
+        }), findingRef);
+        return {
+            cwd: targetCwd,
+            ...payload,
+        };
+    }, (value) => `Started fix review scan for ${String(value.findingRef)}.`));
     server.registerTool("apex-export-findings", {
         title: "Export Apex Findings",
         description: "Export findings for the latest or selected Apex scan to a file on disk.",

package/dist/shell.js

@@ -1,14 +1,14 @@
 import { SHELL_HELP_TEXT } from "./help.js";
-import { commandCancelScan, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindingComment, commandFindingFeedback, commandFindings, commandLogout, commandScan, commandScans, commandStatus, commandUpdate, commandWorkspace, commandWorkspaceUse, commandWorkspaces, initializeInteractiveSession, openCurrentApexView, } from "./commands.js";
+import { commandCancelScan, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindingComment, commandFindingFeedback, commandFindingFixReview, commandFindings, commandLogout, commandScan, commandScans, commandStatus, commandUpdate, commandWorkspace, commandWorkspaceUse, commandWorkspaces, initializeInteractiveSession, openCurrentApexView, } from "./commands.js";
 import { withFlag } from "./args.js";
 import { printCompanyDetails, printInteractiveSessionSummary, printSourceList, printWorkspaceDetails, } from "./output.js";
 import { readLine } from "./prompt.js";
 import { formatApiError } from "./api-client.js";
 const SHELL_COMPLETIONS = [
     { command: "credits" },
-    { command: "scan", args: ["standard", "audit", "ultra"] },
+    { command: "scan", args: ["standard", "audit", "ultra", "pr"] },
     { command: "scans" },
-    { command: "findings", args: ["comment", "feedback"] },
+    { command: "findings", args: ["comment", "feedback", "fix-review"] },
     { command: "export" },
     { command: "workspaces" },
     { command: "cancel-scan" },
@@ -178,11 +178,25 @@ async function runShellCommand(client, cwd, parsed, shellFlags, session) {
             return {};
         case "scan": {
             const mode = parsed.args[0];
-            if (mode && !["standard", "audit", "ultra"].includes(mode)) {
-                process.stderr.write("Usage: /scan [standard|audit|ultra]\n");
+            if (mode && !["standard", "audit", "ultra", "pr"].includes(mode)) {
+                process.stderr.write("Usage: /scan [standard|audit|ultra|pr] [pr-number]\n");
                 return {};
             }
-            const result = await commandScan(client, cwd, mode ? withFlag(shellFlags, "mode", mode) : shellFlags);
+            const prNumber = mode === "pr" ? parsed.args[1] : null;
+            if (mode === "pr" && !prNumber) {
+                process.stderr.write("Usage: /scan pr <pr-number>\n");
+                return {};
+            }
+            if (mode === "pr" && parsed.args.length > 2) {
+                process.stderr.write("Usage: /scan pr <pr-number>\n");
+                return {};
+            }
+            const commandFlags = mode === "pr" && prNumber
+                ? withFlag(withFlag(shellFlags, "mode", mode), "pr", [prNumber])
+                : mode
+                    ? withFlag(shellFlags, "mode", mode)
+                    : shellFlags;
+            const result = await commandScan(client, cwd, commandFlags);
             return {
                 session: {
                     ...session,
@@ -237,6 +251,15 @@ async function runShellCommand(client, cwd, parsed, shellFlags, session) {
                 });
                 return {};
             }
+            if (parsed.args[0] === "fix-review") {
+                const findingRef = parsed.args[1];
+                if (!findingRef || parsed.args.length > 2) {
+                    process.stderr.write("Usage: /findings fix-review <finding-id|finding-identifier>\n");
+                    return {};
+                }
+                await commandFindingFixReview(client, cwd, shellFlags, findingRef);
+                return {};
+            }
             if (parsed.args.length > 1) {
                 process.stderr.write("Usage: /findings [scan-id]\n");
                 return {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cantinasecurity/apex-cli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Standalone CLI and MCP server for Apex.",
   "private": false,
   "type": "module",

package/skills/apex-cli/SKILL.md

@@ -17,7 +17,9 @@ Workflow:
 4. Call `apex-doctor` before starting a scan if workspace binding or source planning might be unclear.
 5. If the directory is not bound to the right workspace, call `apex-workspaces` and `apex-workspace-use`.
 6. Use `apex-scan`, `apex-status`, `apex-scans`, `apex-findings`, and `apex-export-findings` for the scan lifecycle.
-7. Use `apex-finding-comment` and `apex-finding-feedback` when the user wants to leave review notes or valid/invalid feedback on a finding.
+7. For PR scans, call `apex-scan` with `mode: "pr"` and `pullRequests`.
+8. Use `apex-finding-comment` and `apex-finding-feedback` when the user wants to leave review notes or valid/invalid feedback on a finding.
+9. When an agent creates a fix PR externally, call `apex-finding-feedback` with `status: "valid"`, `labels: ["fixed"]`, and `fixPrUrls`, then call `apex-finding-fix-review` to start the fix review scan.
 
 Guidelines:
 
@@ -26,11 +28,13 @@ Guidelines:
 - `apex-scan` scans the provided `cwd` by default; pass `repoPaths` only when the user asks to scan explicit alternate roots.
 - `apex-doctor` reports whether Apex will use remote materialization or a local snapshot upload for each selected source.
 - Apex can scan plain local directories and dirty git worktrees without provider connections by using local snapshot uploads.
-- Audit scans use `mode: "audit"` in user-facing instructions. The legacy `ultra` mode remains accepted as an alias, but audit scans still require provider-backed GitHub or GitLab sources.
+- Audit scans use `mode: "audit"` in user-facing instructions and request payloads. The legacy `ultra` mode remains accepted as an alias, but audit scans still require provider-backed GitHub or GitLab sources.
+- PR scans use `mode: "pr"` and require one provider-backed GitHub repository plus one or more `pullRequests`.
 - `apex-workspace-use` accepts a workspace name, prefix, or ID.
 - Use `sourceMode: "remote"` only when the user explicitly wants to forbid local snapshot fallbacks.
 - Use `force: true` on `apex-scan` only when the user explicitly wants to replace or overlap an active scan.
 - Prefer `apex-findings` for quick inspection and `apex-export-findings` when the user needs a file artifact.
-- Finding comments and feedback currently require `CANTINA_AUTH_TOKEN` in the MCP server environment because those writes go through the Cantina web-app routes instead of the Apex CLI bearer-token routes.
+- Finding comments, feedback, and fix review scan starts currently require `CANTINA_AUTH_TOKEN` in the MCP server environment because those writes go through the Cantina web-app routes instead of the Apex CLI bearer-token routes.
 - Invalid finding feedback requires `dismissalReason`; valid feedback can include `suggestedSeverity`, including `extreme`.
+- Fix PR callback feedback requires valid feedback with `labels: ["fixed"]` and `fixPrUrls`; start the fix review scan with `apex-finding-fix-review` after saving that feedback.
 - Finding identifiers such as `KERN2-25` resolve against the selected or latest scan for the current workspace binding. Pass an explicit scan when needed, or use the finding UUID directly.