@zivis/mcp 0.1.0-alpha.9 → 0.1.6

package/dist/tools/security-review.d.ts

@@ -1,19 +1,3 @@
-/**
- * zivis_security_review — AI-powered security code review with ZIVIS intelligence
- *
- * Composite tool that gathers security context from multiple ZIVIS sources
- * and returns it as structured input for Claude to use during code review.
- *
- * Sources:
- * 1. Historical findings (resolved) — regression check patterns
- * 2. Open findings — known vulnerabilities to verify aren't reintroduced
- * 3. Threat model security controls — what's expected to be in place
- * 4. Threat model attack scenarios — known attack vectors
- * 5. OSS trust data — dependency risk signals
- *
- * This tool does NOT run scans itself. It assembles intelligence from ZIVIS
- * so Claude can perform an informed, context-aware code review.
- */
 import { z } from "zod";
 import type { ApiClient } from "../api-client.js";
 import type { ZivisConfig } from "../types.js";

package/dist/tools/security-review.js

@@ -1,19 +1,3 @@
-/**
- * zivis_security_review — AI-powered security code review with ZIVIS intelligence
- *
- * Composite tool that gathers security context from multiple ZIVIS sources
- * and returns it as structured input for Claude to use during code review.
- *
- * Sources:
- * 1. Historical findings (resolved) — regression check patterns
- * 2. Open findings — known vulnerabilities to verify aren't reintroduced
- * 3. Threat model security controls — what's expected to be in place
- * 4. Threat model attack scenarios — known attack vectors
- * 5. OSS trust data — dependency risk signals
- *
- * This tool does NOT run scans itself. It assembles intelligence from ZIVIS
- * so Claude can perform an informed, context-aware code review.
- */
 import { z } from "zod";
 import { resolveApplicationId } from "../resolve-application-id.js";
 import { sanitizeResponse } from "../sanitize.js";
@@ -60,7 +44,6 @@ export const SECURITY_REVIEW_SCHEMA = {
         .optional()
         .describe("Specific dependencies to check trust scores for (owner/repo format)"),
 };
-// Severity ordering for threshold filtering
 const SEVERITY_ORDER = {
     critical: 5,
     high: 4,
@@ -89,7 +72,6 @@ export function createSecurityReviewHandler(apiClient, config) {
             parameters: { repo, application_id, threat_model_id, campaign_id },
         };
         const errors = [];
-        // ── 1. Historical findings (regression check) ──
         if (shouldInclude("regression") && (repo || application_id)) {
             try {
                 const resolvedFindings = await fetchFindings(apiClient, {
@@ -102,7 +84,6 @@ export function createSecurityReviewHandler(apiClient, config) {
                     status: "false_positive",
                     limit: 20,
                 });
-                // Build regression patterns: group by category/CWE
                 const regressionPatterns = buildRegressionPatterns(resolvedFindings);
                 context.regressionCheck = {
                     _instruction: "Check code changes against these previously fixed vulnerabilities. Flag if similar patterns appear.",
@@ -116,7 +97,6 @@ export function createSecurityReviewHandler(apiClient, config) {
                 errors.push(`Regression data: ${err instanceof Error ? err.message : "failed"}`);
             }
         }
-        // ── 2. Open findings (known vulnerabilities) ──
         if (shouldInclude("regression") && (repo || application_id)) {
             try {
                 const minSeverity = SEVERITY_ORDER[severity_threshold] || 2;
@@ -125,7 +105,6 @@ export function createSecurityReviewHandler(apiClient, config) {
                     status: "open",
                     limit: 50,
                 });
-                // Filter by severity threshold
                 const filtered = openFindings.filter((f) => (SEVERITY_ORDER[f.severity] || 1) >= minSeverity);
                 context.openVulnerabilities = {
                     _instruction: "These are KNOWN open vulnerabilities. Check if code changes interact with or worsen these issues.",
@@ -138,64 +117,76 @@ export function createSecurityReviewHandler(apiClient, config) {
                 errors.push(`Open findings: ${err instanceof Error ? err.message : "failed"}`);
             }
         }
-        // ── 3. Threat model: security controls ──
-        if (shouldInclude("controls") && threat_model_id) {
+        if ((shouldInclude("controls") || shouldInclude("attack_scenarios")) && threat_model_id) {
+            let tm = null;
             try {
-                const tm = await apiClient.get(`/api/threat-models/${threat_model_id}?include=all`);
-                const controls = tm.securityControls || [];
-                const notImplemented = controls.filter((c) => c.status === "not_implemented");
-                const partial = controls.filter((c) => c.status === "partial");
-                const implemented = controls.filter((c) => c.status === "implemented");
-                context.securityControls = {
-                    _instruction: "Verify that code implements these expected security controls. Flag missing or weak implementations.",
-                    summary: {
-                        implemented: implemented.length,
-                        partial: partial.length,
-                        notImplemented: notImplemented.length,
-                    },
-                    gapControls: [...notImplemented, ...partial].map((c) => ({
-                        name: c.name,
-                        type: c.controlType,
-                        status: c.status,
-                        description: c.description,
-                        effectiveness: c.effectivenessRating,
-                    })),
-                    implementedControls: implemented.map((c) => ({
-                        name: c.name,
-                        type: c.controlType,
-                        description: c.description,
-                    })),
-                };
+                tm = await apiClient.get(`/api/threat-models/${threat_model_id}?include=all`);
             }
             catch (err) {
-                errors.push(`Security controls: ${err instanceof Error ? err.message : "failed"}`);
+                errors.push(`Threat model fetch: ${err instanceof Error ? err.message : "failed"}`);
             }
-        }
-        // ── 4. Threat model: attack scenarios ──
-        if (shouldInclude("attack_scenarios") && threat_model_id) {
-            try {
-                const tm = await apiClient.get(`/api/threat-models/${threat_model_id}?include=all`);
-                const scenarios = tm.attackScenarios || [];
-                const minSeverity = SEVERITY_ORDER[severity_threshold] || 2;
-                const filtered = scenarios.filter((s) => (SEVERITY_ORDER[s.severity] || 1) >= minSeverity);
-                context.attackScenarios = {
-                    _instruction: "Review code for susceptibility to these known attack vectors. Check that mitigations are in place.",
-                    count: filtered.length,
-                    scenarios: filtered.map((s) => ({
-                        name: s.name,
-                        strideCategory: s.strideCategory,
-                        severity: s.severity,
-                        likelihood: s.likelihood,
-                        attackVector: s.attackVector,
-                        description: s.description,
-                    })),
-                };
+            const versions = Array.isArray(tm?.versions) ? tm.versions : [];
+            const latestVersion = versions[0] || {};
+            if (tm && shouldInclude("controls")) {
+                try {
+                    const controls = Array.isArray(latestVersion.securityControls)
+                        ? latestVersion.securityControls
+                        : [];
+                    const notImplemented = controls.filter((c) => c.status === "not_implemented");
+                    const partial = controls.filter((c) => c.status === "partial");
+                    const implemented = controls.filter((c) => c.status === "implemented");
+                    context.securityControls = {
+                        _instruction: "Verify that code implements these expected security controls. Flag missing or weak implementations.",
+                        summary: {
+                            implemented: implemented.length,
+                            partial: partial.length,
+                            notImplemented: notImplemented.length,
+                        },
+                        gapControls: [...notImplemented, ...partial].map((c) => ({
+                            name: c.name,
+                            type: c.controlType,
+                            status: c.status,
+                            description: c.description,
+                            effectiveness: c.effectivenessRating,
+                        })),
+                        implementedControls: implemented.map((c) => ({
+                            name: c.name,
+                            type: c.controlType,
+                            description: c.description,
+                        })),
+                    };
+                }
+                catch (err) {
+                    errors.push(`Security controls: ${err instanceof Error ? err.message : "failed"}`);
+                }
             }
-            catch (err) {
-                errors.push(`Attack scenarios: ${err instanceof Error ? err.message : "failed"}`);
+            if (tm && shouldInclude("attack_scenarios")) {
+                try {
+                    const scenarios = Array.isArray(latestVersion.attackScenarios)
+                        ? latestVersion.attackScenarios
+                        : [];
+                    const minSeverity = SEVERITY_ORDER[severity_threshold] || 2;
+                    const filtered = scenarios.filter((s) => (SEVERITY_ORDER[s.severity] || 1) >= minSeverity);
+                    context.attackScenarios = {
+                        _instruction: "Review code for susceptibility to these known attack vectors. Check that mitigations are in place.",
+                        count: filtered.length,
+                        scenarios: filtered.map((s) => ({
+                            displayId: s.displayId,
+                            title: s.title,
+                            strideCategory: s.strideCategory,
+                            severity: s.severity,
+                            likelihood: s.likelihood,
+                            riskScore: s.riskScore,
+                            status: s.status,
+                            narrative: s.narrative,
+                        })),
+                    };
+                }
+                catch (err) {
+                    errors.push(`Attack scenarios: ${err instanceof Error ? err.message : "failed"}`);
+                }
             }
         }
-        // ── 5. Dependency trust scores ──
         if (shouldInclude("dependencies") && dependency_list && dependency_list.length > 0) {
             const depResults = [];
             const baseUrl = config.apiBaseUrl;
@@ -238,7 +229,6 @@ export function createSecurityReviewHandler(apiClient, config) {
                 dependencies: depResults,
             };
         }
-        // ── 6. Campaign findings (if campaign_id provided) ──
         if (campaign_id) {
             try {
                 const campaignFindings = await apiClient.get(`/api/campaigns/${campaign_id}/findings?limit=50`);
@@ -256,7 +246,6 @@ export function createSecurityReviewHandler(apiClient, config) {
                 errors.push(`Campaign findings: ${err instanceof Error ? err.message : "failed"}`);
             }
         }
-        // ── Build review guidance ──
         context.reviewGuidance = buildReviewGuidance(context);
         if (errors.length > 0) {
             context.warnings = errors;
@@ -269,7 +258,6 @@ export function createSecurityReviewHandler(apiClient, config) {
         };
     };
 }
-// ── Helpers ──
 async function fetchFindings(apiClient, params) {
     const query = new URLSearchParams();
     if (params.repo)
@@ -303,7 +291,6 @@ function countBySeverity(findings) {
     return counts;
 }
 function buildRegressionPatterns(resolvedFindings) {
-    // Group by category + CWE to find recurring vulnerability patterns
     const patternMap = new Map();
     for (const f of resolvedFindings) {
         const key = `${f.category || "uncategorized"}::${f.cweId || "no-cwe"}`;
@@ -375,4 +362,3 @@ function parseRepo(input) {
     }
     return null;
 }
-//# sourceMappingURL=security-review.js.map

package/dist/tools/threat-get-capsule.d.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+export declare const THREAT_GET_CAPSULE_NAME = "zivis_threat_get_capsule";
+export declare const THREAT_GET_CAPSULE_DESCRIPTION = "Return the full capsule for a single threat-model pattern.\n\nUse after zivis_threat_list_relevant_capsules has surfaced an id the user wants to dig into. The capsule includes:\n- safe_summary, detect_when, risk_hints, architectural_signals \u2014 for explaining the pattern in threat-model language\n- threats[] with STRIDE categories and remediations \u2014 for grounding the conversation in component/flow/boundary terms\n- repair_contract.allowed / forbidden \u2014 what refactors are safe\n- related_patterns \u2014 adjacent ids in the library\n- model_task_prompt_ref \u2014 pass to zivis_threat_get_inference_prompt to get the prompt the host LLM should run for a deeper check\n\nCapsule data is read from the local pack (~/Library/Caches/zivis/pattern-packs/) with SHA256 integrity verification on every read.";
+export declare const THREAT_GET_CAPSULE_SCHEMA: {
+    capsule_id: z.ZodString;
+};
+export declare function createThreatGetCapsuleHandler(): (params: {
+    capsule_id: string;
+}) => Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}>;

package/dist/tools/threat-get-capsule.js

@@ -0,0 +1,53 @@
+import { z } from "zod";
+import { loadActivePack, getCapsule, listCapsuleIds } from "../pattern-pack/index.js";
+import { withNextSteps, withNextStepsError } from "../lib/next-steps.js";
+export const THREAT_GET_CAPSULE_NAME = "zivis_threat_get_capsule";
+export const THREAT_GET_CAPSULE_DESCRIPTION = `Return the full capsule for a single threat-model pattern.
+
+Use after zivis_threat_list_relevant_capsules has surfaced an id the user wants to dig into. The capsule includes:
+- safe_summary, detect_when, risk_hints, architectural_signals — for explaining the pattern in threat-model language
+- threats[] with STRIDE categories and remediations — for grounding the conversation in component/flow/boundary terms
+- repair_contract.allowed / forbidden — what refactors are safe
+- related_patterns — adjacent ids in the library
+- model_task_prompt_ref — pass to zivis_threat_get_inference_prompt to get the prompt the host LLM should run for a deeper check
+
+Capsule data is read from the local pack (~/Library/Caches/zivis/pattern-packs/) with SHA256 integrity verification on every read.`;
+export const THREAT_GET_CAPSULE_SCHEMA = {
+    capsule_id: z
+        .string()
+        .describe("Capsule id, e.g. 'agents.privilege-separation'. Discoverable via zivis_threat_list_relevant_capsules."),
+};
+export function createThreatGetCapsuleHandler() {
+    return async (params) => {
+        const handle = await loadActivePack();
+        let capsule;
+        try {
+            capsule = await getCapsule(handle, params.capsule_id);
+        }
+        catch (err) {
+            const ids = await listCapsuleIds(handle);
+            return withNextStepsError(`Capsule '${params.capsule_id}' not found in pack ${handle.manifest.pack_id}@${handle.manifest.version}. ${err.message}`, [
+                {
+                    id: "list_relevant_capsules_first",
+                    label: "Find relevant capsules for the current repo first",
+                    tool: "zivis_threat_list_relevant_capsules",
+                    why: "Returns ids you can pass back into zivis_threat_get_capsule.",
+                },
+            ], `Available capsule ids in this pack: ${ids.join(", ")}`);
+        }
+        return withNextSteps({
+            pack: { id: handle.manifest.pack_id, version: handle.manifest.version },
+            capsule,
+        }, capsule.model_task_prompt_ref
+            ? [
+                {
+                    id: "get_inference_prompt",
+                    label: "Get the inference prompt template the host LLM should run",
+                    tool: "zivis_threat_get_inference_prompt",
+                    args_hint: { capsule_id: capsule.id },
+                    why: "Inference prompt + expected_output_schema together form the prompt bundle the IDE LLM executes.",
+                },
+            ]
+            : [], `Capsule ${capsule.id}@${capsule.version} (${capsule.lifecycle}, ${capsule.sensitivity_level ?? "unspecified-tier"}). Threats: ${(capsule.threats?.length ?? 0)}.`);
+    };
+}

package/dist/tools/threat-get-inference-prompt.d.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+export declare const THREAT_GET_INFERENCE_PROMPT_NAME = "zivis_threat_get_inference_prompt";
+export declare const THREAT_GET_INFERENCE_PROMPT_DESCRIPTION = "Return the prompt bundle for the host LLM to run local inference for a capsule.\n\nZIVIS doesn't run an LLM itself \u2014 the host (Cursor, Claude Code, etc.) does. This tool returns the prompt template + structured output schema + ambient capsule context so the host model can run the inference and produce JSON the inferred lane accepts.\n\nUse this when:\n- After zivis_threat_get_capsule, the user wants the host LLM to actually evaluate whether the pattern is present in the code\n- The user says \"go check if my code does this\" / \"is this pattern actually in my repo\"\n- The matcher emits an INFER candidate that needs host-LLM evaluation\n\nThe bundle includes:\n- prompt: the markdown inference prompt\n- expected_output_schema: JSON Schema for the structured response\n- safe_summary: ambient capsule context\n- minimum_context_required: hint to the host for how much code to attach\n- evidence_focus: spans the deterministic strategies already flagged\n\nThe host LLM is expected to gather the indicated code spans, fill in the prompt, return JSON matching the schema. That output then flows back into the inferred lane.";
+export declare const THREAT_GET_INFERENCE_PROMPT_SCHEMA: {
+    capsule_id: z.ZodString;
+};
+export declare function createThreatGetInferencePromptHandler(): (params: {
+    capsule_id: string;
+}) => Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}>;

package/dist/tools/threat-get-inference-prompt.js

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import { loadActivePack, getCapsule, getInferencePrompt } from "../pattern-pack/index.js";
+import { withNextSteps, withNextStepsError } from "../lib/next-steps.js";
+export const THREAT_GET_INFERENCE_PROMPT_NAME = "zivis_threat_get_inference_prompt";
+export const THREAT_GET_INFERENCE_PROMPT_DESCRIPTION = `Return the prompt bundle for the host LLM to run local inference for a capsule.
+
+ZIVIS doesn't run an LLM itself — the host (Cursor, Claude Code, etc.) does. This tool returns the prompt template + structured output schema + ambient capsule context so the host model can run the inference and produce JSON the inferred lane accepts.
+
+Use this when:
+- After zivis_threat_get_capsule, the user wants the host LLM to actually evaluate whether the pattern is present in the code
+- The user says "go check if my code does this" / "is this pattern actually in my repo"
+- The matcher emits an INFER candidate that needs host-LLM evaluation
+
+The bundle includes:
+- prompt: the markdown inference prompt
+- expected_output_schema: JSON Schema for the structured response
+- safe_summary: ambient capsule context
+- minimum_context_required: hint to the host for how much code to attach
+- evidence_focus: spans the deterministic strategies already flagged
+
+The host LLM is expected to gather the indicated code spans, fill in the prompt, return JSON matching the schema. That output then flows back into the inferred lane.`;
+export const THREAT_GET_INFERENCE_PROMPT_SCHEMA = {
+    capsule_id: z
+        .string()
+        .describe("Capsule id whose INFER prompt should be returned (e.g. 'agents.privilege-separation')."),
+};
+export function createThreatGetInferencePromptHandler() {
+    return async (params) => {
+        const handle = await loadActivePack();
+        let capsule;
+        try {
+            capsule = await getCapsule(handle, params.capsule_id);
+        }
+        catch (err) {
+            return withNextStepsError(`Capsule '${params.capsule_id}' not found. ${err.message}`, [
+                {
+                    id: "list_relevant_capsules_first",
+                    label: "List relevant capsules for the current repo first",
+                    tool: "zivis_threat_list_relevant_capsules",
+                    why: "Returns ids you can pass back here.",
+                },
+            ], "Capsule not found — list first to discover ids.");
+        }
+        if (!capsule.model_task_prompt_ref) {
+            return withNextStepsError(`Capsule '${capsule.id}' has no inference prompt defined (model_task_prompt_ref missing). This capsule is deterministic-only.`, [
+                {
+                    id: "get_capsule",
+                    label: "Read the full capsule to see its deterministic strategies",
+                    tool: "zivis_threat_get_capsule",
+                    args_hint: { capsule_id: capsule.id },
+                    why: "Some capsules have no INFER strategy — only AST/GRAPH/META/etc. that the matcher runs locally.",
+                },
+            ], "No inference prompt for this capsule (deterministic only).");
+        }
+        const promptText = await getInferencePrompt(handle, capsule.model_task_prompt_ref);
+        return withNextSteps({
+            pack: { id: handle.manifest.pack_id, version: handle.manifest.version },
+            capsule_id: capsule.id,
+            prompt: promptText,
+            expected_output_schema: capsule.expected_output_schema ?? null,
+            safe_summary: capsule.safe_summary ?? null,
+            minimum_context_required: capsule.minimum_context_required ?? null,
+            host_instructions: "Gather the code spans indicated by minimum_context_required.symbols (or any deterministic match spans the matcher already flagged), attach them to the prompt above, run inference with your model, and return JSON matching expected_output_schema. The structured output flows back into the inferred lane.",
+        }, [
+            {
+                id: "host_runs_inference",
+                label: "Host LLM runs inference now (no further tool call)",
+                tool: "zivis_threat_get_inference_prompt",
+                why: "MCP cannot invoke your model. The host orchestrates the inference using this bundle.",
+            },
+        ], `Prompt bundle ready for host-side inference of ${capsule.id}.`);
+    };
+}

package/dist/tools/threat-list-relevant-capsules.d.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+export declare const THREAT_LIST_RELEVANT_CAPSULES_NAME = "zivis_threat_list_relevant_capsules";
+export declare const THREAT_LIST_RELEVANT_CAPSULES_DESCRIPTION = "List threat-model patterns relevant to the user's current repo.\n\nUse this when the user asks any of:\n- \"what should I be worried about in this code\"\n- \"what threats apply to my app\"\n- \"are there known patterns that match my architecture\"\n- \"what's in my threat model\"\n- mid-conversation when the user describes a feature that touches deps the threat library covers\n\nReads the latest local repo graph artifact (produced by 'zivis inspect') from the user cache, runs every capsule's relevance_filter against it, and returns the subset whose filter passes \u2014 together with each capsule's safe_summary so you can frame the conversation in threat-model terms (component, flow, trust boundary, scenario).\n\nIf no graph artifact exists yet for this repo, the tool returns a next-step pointing to 'zivis inspect'. Always speak in threat-model vocabulary even when the user doesn't.";
+export declare const THREAT_LIST_RELEVANT_CAPSULES_SCHEMA: {
+    artifact_path: z.ZodOptional<z.ZodString>;
+    cwd: z.ZodOptional<z.ZodString>;
+};
+export declare function createThreatListRelevantCapsulesHandler(): (params: {
+    artifact_path?: string;
+    cwd?: string;
+}) => Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}>;

package/dist/tools/threat-list-relevant-capsules.js

@@ -0,0 +1,158 @@
+import { z } from "zod";
+import * as fs from "node:fs/promises";
+import * as fssync from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { loadActivePack, findRelevantCapsules, } from "../pattern-pack/index.js";
+import { withNextSteps, withNextStepsError } from "../lib/next-steps.js";
+export const THREAT_LIST_RELEVANT_CAPSULES_NAME = "zivis_threat_list_relevant_capsules";
+export const THREAT_LIST_RELEVANT_CAPSULES_DESCRIPTION = `List threat-model patterns relevant to the user's current repo.
+
+Use this when the user asks any of:
+- "what should I be worried about in this code"
+- "what threats apply to my app"
+- "are there known patterns that match my architecture"
+- "what's in my threat model"
+- mid-conversation when the user describes a feature that touches deps the threat library covers
+
+Reads the latest local repo graph artifact (produced by 'zivis inspect') from the user cache, runs every capsule's relevance_filter against it, and returns the subset whose filter passes — together with each capsule's safe_summary so you can frame the conversation in threat-model terms (component, flow, trust boundary, scenario).
+
+If no graph artifact exists yet for this repo, the tool returns a next-step pointing to 'zivis inspect'. Always speak in threat-model vocabulary even when the user doesn't.`;
+export const THREAT_LIST_RELEVANT_CAPSULES_SCHEMA = {
+    artifact_path: z
+        .string()
+        .optional()
+        .describe("Optional path to a specific RepoGraphArtifactV1 JSON. If omitted, the tool finds the most recent artifact in ~/Library/Caches/zivis/repos/<repo-id>/inspect/runs/ for the repo at cwd."),
+    cwd: z
+        .string()
+        .optional()
+        .describe("Working directory whose repo cache to search (defaults to server cwd)."),
+};
+export function createThreatListRelevantCapsulesHandler() {
+    return async (params) => {
+        const cwd = params.cwd ?? process.cwd();
+        let artifact;
+        let artifactPath;
+        try {
+            const resolved = await resolveArtifactPath(params.artifact_path, cwd);
+            artifactPath = resolved;
+            const raw = await fs.readFile(resolved, "utf8");
+            artifact = JSON.parse(raw);
+        }
+        catch (err) {
+            return withNextStepsError(`No repo graph artifact found. ${err.message}`, [
+                {
+                    id: "run_zivis_inspect",
+                    label: "Run `zivis inspect` to build the local repo graph",
+                    tool: "zivis_inspect",
+                    why: "The relevance evaluation reads from the latest inspect run in the user cache.",
+                },
+            ], "Run `zivis inspect` first; this tool reads from its output.");
+        }
+        const handle = await loadActivePack();
+        const relevant = await findRelevantCapsules(handle, artifact);
+        const summaries = relevant.map((cap) => ({
+            id: cap.id,
+            title: cap.title,
+            category: cap.category,
+            safe_summary: cap.safe_summary,
+            applicable_languages: cap.applicable_languages,
+            matched_on: matchedTerms(cap, artifact),
+        }));
+        return withNextSteps({
+            artifact_path: artifactPath,
+            pack: { id: handle.manifest.pack_id, version: handle.manifest.version },
+            languages_in_scope: artifact.scope.languages ?? [],
+            relevant_count: summaries.length,
+            relevant_capsules: summaries,
+        }, summaries.length > 0
+            ? [
+                {
+                    id: "get_capsule_details",
+                    label: "Pull the full capsule for any item the user wants to investigate",
+                    tool: "zivis_threat_get_capsule",
+                    why: "The full capsule has threats (with STRIDE), risk_hints, repair_contract, related_patterns.",
+                },
+                {
+                    id: "get_inference_prompt",
+                    label: "Get the inference prompt for the host LLM to run a deeper check",
+                    tool: "zivis_threat_get_inference_prompt",
+                    why: "INFER strategies in each capsule reference a prompt template the user's IDE model executes.",
+                },
+            ]
+            : [
+                {
+                    id: "no_relevant_patterns",
+                    label: "No public-pack patterns matched this repo",
+                    tool: "zivis_threat_list_relevant_capsules",
+                    why: "This is normal for repos without agentic / RAG / self-consistency / multi-tenant patterns. Proprietary patterns may still apply server-side.",
+                },
+            ], summaries.length > 0
+            ? `Found ${summaries.length} relevant capsule(s) in the threat library.`
+            : "No public-pack capsules matched this repo. Proprietary patterns evaluated server-side may still apply.");
+    };
+}
+function userCacheRoot() {
+    const home = os.homedir();
+    if (process.platform === "darwin") {
+        return path.join(home, "Library", "Caches", "zivis");
+    }
+    if (process.platform === "win32") {
+        const localAppData = process.env.LOCALAPPDATA ?? path.join(home, "AppData", "Local");
+        return path.join(localAppData, "zivis", "Cache");
+    }
+    const xdg = process.env.XDG_CACHE_HOME;
+    return path.join(xdg ?? path.join(home, ".cache"), "zivis");
+}
+async function resolveArtifactPath(explicit, cwd) {
+    if (explicit) {
+        if (!fssync.existsSync(explicit)) {
+            throw new Error(`Artifact path does not exist: ${explicit}`);
+        }
+        return explicit;
+    }
+    const reposRoot = path.join(userCacheRoot(), "repos");
+    if (!fssync.existsSync(reposRoot)) {
+        throw new Error(`No inspect cache found at ${reposRoot}. Run \`zivis inspect\` from the repo to populate it.`);
+    }
+    const candidates = [];
+    for (const repo of await fs.readdir(reposRoot, { withFileTypes: true })) {
+        if (!repo.isDirectory())
+            continue;
+        const runs = path.join(reposRoot, repo.name, "inspect", "runs");
+        if (!fssync.existsSync(runs))
+            continue;
+        for (const entry of await fs.readdir(runs)) {
+            if (!entry.endsWith(".json"))
+                continue;
+            const full = path.join(runs, entry);
+            const stat = await fs.stat(full);
+            candidates.push({ file: full, mtime: stat.mtimeMs });
+        }
+    }
+    if (candidates.length === 0) {
+        throw new Error(`No inspect runs found under ${reposRoot}. Run \`zivis inspect\` from the repo to produce one.`);
+    }
+    candidates.sort((a, b) => b.mtime - a.mtime);
+    return candidates[0].file;
+}
+function matchedTerms(cap, artifact) {
+    const matched = [];
+    const pkgs = new Set();
+    for (const node of artifact.nodes) {
+        if (node.type === "external_dependency" && node.attributes?.package) {
+            pkgs.add(node.attributes.package);
+        }
+    }
+    const langs = new Set(artifact.scope.languages ?? []);
+    const f = cap.relevance_filter;
+    if (!f)
+        return ["always-applicable (no relevance_filter set)"];
+    for (const term of [...(f.any_of ?? []), ...(f.all_of ?? [])]) {
+        if (term.dependency && pkgs.has(term.dependency))
+            matched.push(`dep:${term.dependency}`);
+        if (term.language && langs.has(term.language))
+            matched.push(`language:${term.language}`);
+    }
+    return matched.length > 0 ? matched : ["language match only"];
+}

package/dist/tools/threat-run-matcher.d.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+export declare const THREAT_RUN_MATCHER_NAME = "zivis_threat_run_matcher";
+export declare const THREAT_RUN_MATCHER_DESCRIPTION = "Run the local pattern matcher against the latest repo graph artifact and emit normalized threat findings.\n\nUse this when:\n- The user asks ZIVIS to actually evaluate (not just list) which patterns fire on their code\n- After 'zivis inspect' has produced an artifact and the user wants concrete findings\n- \"find security issues in my code\", \"check this against the threat library\", \"what's actually wrong here\"\n\nPhase 3 v1 evaluates AST strategies for real (via @ast-grep/napi for TS/JS, plus Python and Go via dynamic language packs). INFER strategies emit a candidate the host LLM is expected to pick up via zivis_threat_get_inference_prompt and run with its own model. GRAPH / META / DEP / CONFIG strategies are surfaced as fired_strategies with match_count: 0 \u2014 visible-but-not-evaluated for now.\n\nLane assignment per finding:\n- trusted: count of fired deterministic strategies meets the capsule's required_evidence_count\n- inferred: at least one strategy fired but the bar wasn't met (host should run inference to confirm)\n\nThe output is a normalized findings array with pattern_id, lane, confidence, evidence spans, and (for inferred-lane findings) an inference_candidate the host LLM uses to run deeper analysis.";
+export declare const THREAT_RUN_MATCHER_SCHEMA: {
+    artifact_path: z.ZodOptional<z.ZodString>;
+    cwd: z.ZodOptional<z.ZodString>;
+};
+export declare function createThreatRunMatcherHandler(): (params: {
+    artifact_path?: string;
+    cwd?: string;
+}) => Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}>;