@zivis/mcp 0.1.19 → 0.2.5

package/dist/tools/document.js

@@ -0,0 +1,137 @@
+import { z } from "zod";
+import { sanitizeResponse, sanitizeInboundText } from "../sanitize.js";
+import { requireApplicationId } from "../resolve-application-id.js";
+export const DOCUMENT_NAME = "zivis_document";
+export const DOCUMENT_DESCRIPTION = `CRUD for narrative markdown documents under a ThreatModel (exec summaries, remediation plans, architecture narratives). Can embed Diagrams (see zivis_diagram) via \`\`\`mermaid or \`\`\`zivis:diagram (UUID) fenced blocks.
+
+action:
+- create: requires title, exactly one of threat_model_id or entity_type+entity_id — or omit both threat_model_id and entity_type/entity_id entirely to attach to the current workspace's bound Application automatically. entity_type "application" with no entity_id also auto-resolves from that binding. Optional content, tags.
+- get: requires document_id. Full markdown + metadata.
+- list: optional threat_model_id or entity_type+entity_id, search filters.
+- update: requires document_id + at least one of title/content/tags. content REPLACES the whole document — get first, then send the complete edited markdown, preserving unrelated structure.`;
+const ENTITY_TYPE_ENUM = [
+    "application",
+    "threat_model",
+    "agent_instance",
+    "scan",
+    "finding",
+    "attack_scenario",
+    "component",
+    "trust_room",
+    "campaign",
+];
+export const DOCUMENT_SCHEMA = {
+    action: z.enum(["create", "get", "list", "update"]).describe("Which document operation to perform"),
+    threat_model_id: z.string().optional().describe("UUID of the parent threat model. For create, alternative to entity_type+entity_id — provide exactly one, not both. Optional filter for list."),
+    title: z.string().optional().describe("Document title. Required for create."),
+    content: z.string().optional().describe("Markdown content. For update, REPLACES the entire document."),
+    tags: z.array(z.string()).optional().describe("Tags. For update, replaces existing tags."),
+    document_id: z.string().optional().describe("UUID of the document. Required for get and update."),
+    entity_type: z.enum(ENTITY_TYPE_ENUM).optional().describe("Polymorphic parent entity type, for attaching a document directly to something other than a ThreatModel (e.g. an Application with no ThreatModel). For create, alternative to threat_model_id — provide exactly one, not both. Must be paired with entity_id. Optional filter for list (also paired with entity_id)."),
+    entity_id: z.string().optional().describe("UUID of the entity_type target. Must be paired with entity_type."),
+    search: z.string().optional().describe("Filter by title (case-insensitive substring) or tag. Used by list."),
+};
+function errorResult(message) {
+    return {
+        content: [{ type: "text", text: `Error: ${message}` }],
+        isError: true,
+    };
+}
+function successResult(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(sanitizeResponse(data), null, 2) }],
+    };
+}
+export function createDocumentHandler(apiClient) {
+    return async (params) => {
+        try {
+            switch (params.action) {
+                case "create": {
+                    const { threat_model_id, title, content, tags, entity_type, entity_id } = params;
+                    if (!title || !title.trim())
+                        return errorResult("title is required for create");
+                    const hasTm = !!threat_model_id;
+                    let hasEntityType = !!entity_type;
+                    let hasEntityId = !!entity_id;
+                    let resolvedEntityType = entity_type;
+                    let resolvedEntityId = entity_id;
+                    if (!hasTm && !hasEntityType && !hasEntityId) {
+                        const req = requireApplicationId(undefined);
+                        if (!req.ok)
+                            return errorResult(req.message);
+                        resolvedEntityType = "application";
+                        resolvedEntityId = req.id;
+                        hasEntityType = true;
+                        hasEntityId = true;
+                    }
+                    else if (!hasTm && entity_type === "application" && !hasEntityId) {
+                        const req = requireApplicationId(undefined);
+                        if (!req.ok)
+                            return errorResult(req.message);
+                        resolvedEntityId = req.id;
+                        hasEntityId = true;
+                    }
+                    if (hasEntityType !== hasEntityId) {
+                        return errorResult("entity_type and entity_id must be provided together");
+                    }
+                    const hasEntity = hasEntityType && hasEntityId;
+                    if (hasTm && hasEntity) {
+                        return errorResult("Provide either threat_model_id or entity_type+entity_id, not both");
+                    }
+                    if (!hasTm && !hasEntity) {
+                        return errorResult("Provide either threat_model_id or entity_type+entity_id");
+                    }
+                    const data = await apiClient.post(`/api/documents`, {
+                        ...(hasTm ? { threatModelId: threat_model_id } : { entityType: resolvedEntityType, entityId: resolvedEntityId }),
+                        title: sanitizeInboundText(title, 500),
+                        content: sanitizeInboundText(content ?? "", 200_000),
+                        tags: tags ?? [],
+                    });
+                    return successResult(data);
+                }
+                case "get": {
+                    if (!params.document_id)
+                        return errorResult("document_id is required for get");
+                    const data = await apiClient.get(`/api/documents/${params.document_id}`);
+                    return successResult(data);
+                }
+                case "list": {
+                    const qs = new URLSearchParams();
+                    if (params.threat_model_id)
+                        qs.set("threatModelId", params.threat_model_id);
+                    if (params.entity_type && params.entity_id) {
+                        qs.set("entityType", params.entity_type);
+                        qs.set("entityId", params.entity_id);
+                    }
+                    if (params.search)
+                        qs.set("search", params.search);
+                    const path = `/api/documents${qs.toString() ? `?${qs.toString()}` : ""}`;
+                    const data = await apiClient.get(path);
+                    return successResult(data);
+                }
+                case "update": {
+                    const { document_id, title, content, tags } = params;
+                    if (!document_id)
+                        return errorResult("document_id is required for update");
+                    if (title === undefined && content === undefined && tags === undefined) {
+                        return errorResult("At least one of title, content, or tags must be provided for update");
+                    }
+                    const body = {};
+                    if (title !== undefined)
+                        body.title = sanitizeInboundText(title, 500);
+                    if (content !== undefined)
+                        body.content = sanitizeInboundText(content, 200_000);
+                    if (tags !== undefined)
+                        body.tags = tags;
+                    const data = await apiClient.patch(`/api/documents/${document_id}`, body);
+                    return successResult({ ok: true, document_id, updated: data });
+                }
+                default:
+                    return errorResult(`Unknown action: ${params.action}`);
+            }
+        }
+        catch (err) {
+            return errorResult(err?.message ?? `Failed to ${params.action} document`);
+        }
+    };
+}

package/dist/tools/finding.d.ts

@@ -0,0 +1,133 @@
+import { z } from "zod";
+import type { ApiClient } from "../api-client.js";
+export declare const FINDING_NAME = "zivis_finding";
+export declare const FINDING_DESCRIPTION = "Create, update, or delete a tracked security finding authored by hand (not from a scanner). Every change is audited.\n\naction:\n- create: requires title, severity. For service-delivered results (pen test/red team/ZRT), pass source_type + producer (requires run_agents permission).\n- update: requires finding_id. Two kinds of change, never mixed in one call:\n    1. Direct edit: title/severity/description/category/remediation_steps/cwe_id/owasp_id, and non-closing status (open|triaged|in_progress).\n    2. Disposition (`disposition`: open|fixed|accepted_by_design|accepted_risk_based|planned|not_applicable, + rationale/ref/owner_name/target_date/review_date/compensating_controls/residual_severity/note) \u2014 records the customer's claim/decision. disposition=fixed does NOT close the finding: status is only ever derived from (disposition, independent verification) \u2014 a claim never closes a finding, only an independent ZIVIS verdict does. Closing values (resolved/dismissed/suppressed) are REJECTED on the direct-edit path; use `disposition` instead.\n- delete: requires finding_id. Soft-delete, manual findings only.";
+export declare const FINDING_SCHEMA: {
+    action: z.ZodEnum<{
+        create: "create";
+        delete: "delete";
+        update: "update";
+    }>;
+    title: z.ZodOptional<z.ZodString>;
+    severity: z.ZodOptional<z.ZodEnum<{
+        critical: "critical";
+        high: "high";
+        medium: "medium";
+        low: "low";
+        info: "info";
+    }>>;
+    description: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodEnum<{
+        vulnerability: "vulnerability";
+        misconfiguration: "misconfiguration";
+        secret: "secret";
+        anomaly: "anomaly";
+        other: "other";
+    }>>;
+    confidence: z.ZodOptional<z.ZodEnum<{
+        high: "high";
+        medium: "medium";
+        low: "low";
+    }>>;
+    application_id: z.ZodOptional<z.ZodString>;
+    source_document_id: z.ZodOptional<z.ZodString>;
+    excerpt: z.ZodOptional<z.ZodString>;
+    evidence_location: z.ZodOptional<z.ZodString>;
+    cwe_id: z.ZodOptional<z.ZodString>;
+    owasp_id: z.ZodOptional<z.ZodString>;
+    remediation_steps: z.ZodOptional<z.ZodString>;
+    source_type: z.ZodOptional<z.ZodEnum<{
+        threat_model: "threat_model";
+        manual: "manual";
+        red_team: "red_team";
+        pen_test: "pen_test";
+    }>>;
+    producer: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodEnum<{
+            human: "human";
+            zrt: "zrt";
+            frontier_tool: "frontier_tool";
+            third_party: "third_party";
+        }>;
+        id: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        toolVersion: z.ZodOptional<z.ZodString>;
+        engagementId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    scenario_id: z.ZodOptional<z.ZodString>;
+    attack_step_id: z.ZodOptional<z.ZodString>;
+    finding_id: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        open: "open";
+        in_progress: "in_progress";
+        triaged: "triaged";
+    }>>;
+    note: z.ZodOptional<z.ZodString>;
+    disposition: z.ZodOptional<z.ZodEnum<{
+        fixed: "fixed";
+        open: "open";
+        accepted_by_design: "accepted_by_design";
+        accepted_risk_based: "accepted_risk_based";
+        planned: "planned";
+        not_applicable: "not_applicable";
+    }>>;
+    rationale: z.ZodOptional<z.ZodString>;
+    ref: z.ZodOptional<z.ZodString>;
+    owner_name: z.ZodOptional<z.ZodString>;
+    target_date: z.ZodOptional<z.ZodString>;
+    review_date: z.ZodOptional<z.ZodString>;
+    compensating_controls: z.ZodOptional<z.ZodString>;
+    residual_severity: z.ZodOptional<z.ZodEnum<{
+        critical: "critical";
+        high: "high";
+        medium: "medium";
+        low: "low";
+        info: "info";
+    }>>;
+    reason: z.ZodOptional<z.ZodString>;
+};
+type Producer = {
+    kind: "human" | "zrt" | "frontier_tool" | "third_party";
+    id?: string;
+    name?: string;
+    toolVersion?: string;
+    engagementId?: string;
+};
+type FindingParams = {
+    action: "create" | "update" | "delete";
+    title?: string;
+    severity?: "critical" | "high" | "medium" | "low" | "info";
+    description?: string;
+    category?: "vulnerability" | "misconfiguration" | "secret" | "anomaly" | "other";
+    confidence?: "high" | "medium" | "low";
+    application_id?: string;
+    source_document_id?: string;
+    excerpt?: string;
+    evidence_location?: string;
+    cwe_id?: string;
+    owasp_id?: string;
+    remediation_steps?: string;
+    source_type?: "manual" | "pen_test" | "red_team" | "threat_model";
+    producer?: Producer;
+    scenario_id?: string;
+    attack_step_id?: string;
+    finding_id?: string;
+    status?: "open" | "triaged" | "in_progress";
+    note?: string;
+    disposition?: "open" | "fixed" | "accepted_by_design" | "accepted_risk_based" | "planned" | "not_applicable";
+    rationale?: string;
+    ref?: string;
+    owner_name?: string;
+    target_date?: string;
+    review_date?: string;
+    compensating_controls?: string;
+    residual_severity?: "critical" | "high" | "medium" | "low" | "info";
+    reason?: string;
+};
+export declare function createFindingHandler(apiClient: ApiClient): (params: FindingParams) => Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export {};

package/dist/tools/finding.js

@@ -0,0 +1,211 @@
+import { z } from "zod";
+import { sanitizeResponse, sanitizeInboundText } from "../sanitize.js";
+import { requireApplicationId } from "../resolve-application-id.js";
+export const FINDING_NAME = "zivis_finding";
+const CLOSING_STATUSES = new Set(["resolved", "dismissed", "suppressed"]);
+export const FINDING_DESCRIPTION = `Create, update, or delete a tracked security finding authored by hand (not from a scanner). Every change is audited.
+
+action:
+- create: requires title, severity. For service-delivered results (pen test/red team/ZRT), pass source_type + producer (requires run_agents permission).
+- update: requires finding_id. Two kinds of change, never mixed in one call:
+    1. Direct edit: title/severity/description/category/remediation_steps/cwe_id/owasp_id, and non-closing status (open|triaged|in_progress).
+    2. Disposition (\`disposition\`: open|fixed|accepted_by_design|accepted_risk_based|planned|not_applicable, + rationale/ref/owner_name/target_date/review_date/compensating_controls/residual_severity/note) — records the customer's claim/decision. disposition=fixed does NOT close the finding: status is only ever derived from (disposition, independent verification) — a claim never closes a finding, only an independent ZIVIS verdict does. Closing values (resolved/dismissed/suppressed) are REJECTED on the direct-edit path; use \`disposition\` instead.
+- delete: requires finding_id. Soft-delete, manual findings only.`;
+export const FINDING_SCHEMA = {
+    action: z.enum(["create", "update", "delete"]).describe("Which finding operation to perform"),
+    title: z.string().optional().describe("Short summary of the finding. Required for create; optional new value for update."),
+    severity: z
+        .enum(["critical", "high", "medium", "low", "info"])
+        .optional()
+        .describe("Required for create. Be honest — reserve critical/high for genuinely exploitable issues."),
+    description: z.string().optional().describe("Details / new description (markdown allowed)."),
+    category: z.enum(["vulnerability", "misconfiguration", "secret", "anomaly", "other"]).optional().describe("Finding category (default on create: vulnerability)."),
+    confidence: z.enum(["high", "medium", "low"]).optional().describe("create only: how confident you are this is real (default: medium)."),
+    application_id: z.string().optional().describe("Application UUID. create only (update/delete resolve the application from the finding itself). Defaults to applicationId in .zivis/project.json if omitted."),
+    source_document_id: z.string().optional().describe("create only: UUID of a ZIVIS Document this finding came from. Links the finding back to it."),
+    excerpt: z.string().optional().describe("create only: the exact source text the finding was drawn from (e.g. the README snippet)."),
+    evidence_location: z.string().optional().describe("create only: human-readable locator, e.g. 'README.md:L40-L51' or a file path."),
+    cwe_id: z.string().optional().describe("Optional CWE id, e.g. 'CWE-89'. create/update."),
+    owasp_id: z.string().optional().describe("Optional OWASP id, e.g. 'A01'. create/update."),
+    remediation_steps: z.string().optional().describe("Remediation guidance. create/update."),
+    source_type: z
+        .enum(["manual", "pen_test", "red_team", "threat_model"])
+        .optional()
+        .describe("create only (default: manual). Non-manual marks the finding as a service-delivered result that flows to the Signal API; requires the run_agents org permission."),
+    producer: z
+        .object({
+        kind: z.enum(["human", "zrt", "frontier_tool", "third_party"]).describe("Who/what produced the finding"),
+        id: z.string().optional().describe("Stable producer identifier (e.g. analyst email)"),
+        name: z.string().optional().describe("Display name (e.g. 'Jake Miller', 'ZRT')"),
+        toolVersion: z.string().optional().describe("Tool version, if applicable"),
+        engagementId: z.string().optional().describe("Engagement/campaign this run belongs to"),
+    })
+        .optional()
+        .describe("create only: producer provenance, stored on the finding as metadata.producer"),
+    scenario_id: z.string().optional().describe("create only: GraphNode logicalId (UUID) of the ATTACK_SCENARIO this finding proves out"),
+    attack_step_id: z.string().optional().describe("create only: GraphNode logicalId (UUID) of the ATTACK_STEP this finding corresponds to"),
+    finding_id: z.string().optional().describe("UUID of the finding. Required for update and delete."),
+    status: z
+        .enum(["open", "triaged", "in_progress"])
+        .optional()
+        .describe("update only: new NON-CLOSING lifecycle status. resolved/dismissed/suppressed are not accepted here — pass `disposition` instead; this tool rejects a closing status client-side rather than round-tripping to the API."),
+    note: z.string().optional().describe("Optional note recorded in the audit history. update only."),
+    disposition: z
+        .enum(["open", "fixed", "accepted_by_design", "accepted_risk_based", "planned", "not_applicable"])
+        .optional()
+        .describe("update only: record the CUSTOMER's claim/decision about this finding. Routes through PATCH /unified/:id/disposition (deriveStatus()) — never closes the finding by itself. Rationale is REQUIRED when disposition is accepted_by_design or accepted_risk_based."),
+    rationale: z.string().optional().describe("update+disposition only: why this disposition — required for accepted_by_design/accepted_risk_based."),
+    ref: z.string().optional().describe("update+disposition only: reference (ticket id, PR link, etc.) backing the disposition."),
+    owner_name: z.string().optional().describe("update+disposition only: who owns this disposition going forward."),
+    target_date: z.string().optional().describe("update+disposition only: ISO date this disposition targets (e.g. a planned fix date)."),
+    review_date: z.string().optional().describe("update+disposition only: ISO date this disposition should be re-reviewed by."),
+    compensating_controls: z.string().optional().describe("update+disposition only: mitigations already in place while this risk is carried."),
+    residual_severity: z.enum(["critical", "high", "medium", "low", "info"]).optional().describe("update+disposition only: severity that remains after compensating controls."),
+    reason: z.string().optional().describe("delete only: short reason for deleting (recorded in audit history)."),
+};
+function errorResult(message) {
+    return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+}
+function successResult(data) {
+    return { content: [{ type: "text", text: JSON.stringify(sanitizeResponse(data), null, 2) }] };
+}
+function resolveApplicationIdSafe(explicit) {
+    const r = requireApplicationId(explicit);
+    return r.ok ? r.id : undefined;
+}
+const ACCEPTED_DISPOSITIONS = new Set(["accepted_by_design", "accepted_risk_based"]);
+export function createFindingHandler(apiClient) {
+    return async (params) => {
+        try {
+            switch (params.action) {
+                case "create": {
+                    if (!params.title || !params.title.trim())
+                        return errorResult("title is required for create");
+                    if (!params.severity)
+                        return errorResult("severity is required for create");
+                    let applicationId;
+                    if (!params.source_document_id) {
+                        const resolved = requireApplicationId(params.application_id);
+                        if (!resolved.ok)
+                            return errorResult(resolved.message);
+                        applicationId = resolved.id;
+                    }
+                    else {
+                        applicationId = resolveApplicationIdSafe(params.application_id);
+                    }
+                    const data = await apiClient.post(`/api/findings/unified`, {
+                        title: sanitizeInboundText(params.title, 500),
+                        severity: params.severity,
+                        description: sanitizeInboundText(params.description, 8000),
+                        category: params.category,
+                        confidence: params.confidence,
+                        origin: "mcp",
+                        applicationId,
+                        sourceDocumentId: params.source_document_id,
+                        excerpt: sanitizeInboundText(params.excerpt, 8000),
+                        evidenceLocation: sanitizeInboundText(params.evidence_location, 500),
+                        cweId: params.cwe_id,
+                        owaspId: params.owasp_id,
+                        remediationSteps: sanitizeInboundText(params.remediation_steps, 4000),
+                        sourceType: params.source_type,
+                        producer: params.producer
+                            ? {
+                                kind: params.producer.kind,
+                                id: sanitizeInboundText(params.producer.id, 300),
+                                name: sanitizeInboundText(params.producer.name, 300),
+                                toolVersion: sanitizeInboundText(params.producer.toolVersion, 300),
+                                engagementId: sanitizeInboundText(params.producer.engagementId, 300),
+                            }
+                            : undefined,
+                        scenarioId: params.scenario_id,
+                        attackStepId: params.attack_step_id,
+                    });
+                    return successResult(data);
+                }
+                case "update": {
+                    if (!params.finding_id || !params.finding_id.trim()) {
+                        return errorResult("finding_id is required for update");
+                    }
+                    const hasDisposition = params.disposition !== undefined;
+                    const hasDirectFields = params.title !== undefined ||
+                        params.severity !== undefined ||
+                        params.description !== undefined ||
+                        params.category !== undefined ||
+                        params.remediation_steps !== undefined ||
+                        params.cwe_id !== undefined ||
+                        params.owasp_id !== undefined ||
+                        params.status !== undefined;
+                    if (hasDisposition && hasDirectFields) {
+                        return errorResult("Provide either `disposition` or direct field/status edits in one call, not both — the disposition write and the content-field write are two different endpoints. Make two calls if you need both.");
+                    }
+                    if (hasDisposition) {
+                        if (ACCEPTED_DISPOSITIONS.has(params.disposition) && !String(params.rationale ?? "").trim()) {
+                            return errorResult("rationale is required when disposition is accepted_by_design or accepted_risk_based");
+                        }
+                        const body = { disposition: params.disposition };
+                        if (params.rationale !== undefined)
+                            body.rationale = sanitizeInboundText(params.rationale, 4000);
+                        if (params.ref !== undefined)
+                            body.ref = sanitizeInboundText(params.ref, 500);
+                        if (params.owner_name !== undefined)
+                            body.ownerName = sanitizeInboundText(params.owner_name, 300);
+                        if (params.target_date !== undefined)
+                            body.targetDate = params.target_date;
+                        if (params.review_date !== undefined)
+                            body.reviewDate = params.review_date;
+                        if (params.compensating_controls !== undefined)
+                            body.compensatingControls = sanitizeInboundText(params.compensating_controls, 2000);
+                        if (params.residual_severity !== undefined)
+                            body.residualSeverity = params.residual_severity;
+                        if (params.note !== undefined)
+                            body.note = sanitizeInboundText(params.note, 4000);
+                        const data = await apiClient.patch(`/api/findings/unified/${encodeURIComponent(params.finding_id)}/disposition`, body);
+                        return successResult(data);
+                    }
+                    if (params.status !== undefined && CLOSING_STATUSES.has(params.status)) {
+                        return errorResult(`"${params.status}" cannot be set directly — it must be derived from disposition + independent verification. ` +
+                            `Pass \`disposition\` instead (fixed, accepted_by_design, accepted_risk_based, not_applicable, planned) to record what you believe/decided; ` +
+                            `only an independent ZIVIS verification can move the finding to a closed status.`);
+                    }
+                    const body = {};
+                    if (params.title !== undefined)
+                        body.title = sanitizeInboundText(params.title, 500);
+                    if (params.severity !== undefined)
+                        body.severity = params.severity;
+                    if (params.description !== undefined)
+                        body.description = sanitizeInboundText(params.description, 8000);
+                    if (params.category !== undefined)
+                        body.category = params.category;
+                    if (params.remediation_steps !== undefined)
+                        body.remediationSteps = sanitizeInboundText(params.remediation_steps, 4000);
+                    if (params.cwe_id !== undefined)
+                        body.cweId = params.cwe_id;
+                    if (params.owasp_id !== undefined)
+                        body.owaspId = params.owasp_id;
+                    if (params.status !== undefined)
+                        body.status = params.status;
+                    if (params.note !== undefined)
+                        body.note = sanitizeInboundText(params.note, 4000);
+                    if (Object.keys(body).length === 0) {
+                        return errorResult("Provide at least one field to update (or `disposition` to record a customer decision)");
+                    }
+                    const data = await apiClient.patch(`/api/findings/unified/${encodeURIComponent(params.finding_id)}`, body);
+                    return successResult(data);
+                }
+                case "delete": {
+                    if (!params.finding_id || !params.finding_id.trim()) {
+                        return errorResult("finding_id is required for delete");
+                    }
+                    const query = params.reason ? `?reason=${encodeURIComponent(params.reason)}` : "";
+                    const data = await apiClient.del(`/api/findings/unified/${encodeURIComponent(params.finding_id)}${query}`);
+                    return successResult(data);
+                }
+                default:
+                    return errorResult(`Unknown action: ${params.action}`);
+            }
+        }
+        catch (err) {
+            return errorResult(err?.message ?? `Failed to ${params.action} finding`);
+        }
+    };
+}

package/dist/tools/get-started.d.ts

@@ -2,7 +2,7 @@ import { z } from "zod";
 import type { ApiClient } from "../api-client.js";
 import type { ZivisConfig } from "../types.js";
 export declare const GET_STARTED_NAME = "zivis_get_started";
-export declare const GET_STARTED_DESCRIPTION = "Call this FIRST on any turn where the user asks about security, vulnerabilities, code review, deployment readiness, threat modeling, dependencies, or \"what should I do next.\" Idempotent and safe to call repeatedly \u2014 detects prior inspect runs and never re-inspects unnecessarily. Prefer this over calling zivis_inspect directly.\n\nUse this when the user says any of:\n- \"what should I do for security on this app\"\n- \"uhh, where do I start\"\n- \"is my app safe\" / \"is my chatbot safe\"\n- \"I need to do security stuff before launch\"\n- \"I have an audit / pen test / customer asking about security\"\n- \"check my dependencies / libraries / repos\"\n- \"how do I use ZIVIS\"\n- \"what can ZIVIS do for me\"\n\nThis tool inspects the current project state \u2014 binding, application, scans, findings \u2014\nAND if a recent 'zivis inspect' artifact exists for this repo, evaluates the local\nthreat library against it to surface architectural patterns ZIVIS thinks may apply\n(self-consistency without context isolation, late org filter, privilege separation, etc.).\nThe 'relevant_threats' field in the response is what makes this tool different from a\ngeneric security menu: ZIVIS is reading the user's actual codebase via the graph\nartifact and naming threats by their architectural shape.\n\nSpeak in plain developer language by default \u2014 do not introduce jargon (actor, STRIDE,\nkill chain, TTPs) unless the user already used it. Naming the actual product concepts\n(\"your threat model\", `zivis threatmodel`) is fine when they are the literal thing being\ndiscussed; that is a product noun, not jargon to avoid.\n\nOutput is a structured JSON object. Present recommended_next_steps as a numbered list\nto the user, in order, and ask them to pick one. If relevant_threats is non-empty, lead\nwith that \u2014 it's the most concrete thing ZIVIS knows about their repo. Use the label\nand why fields verbatim; do not invent new steps. If the user is unsure which to pick,\nrecommend the item flagged in if_user_unsure.";
+export declare const GET_STARTED_DESCRIPTION = "Call this FIRST on any turn where the user asks about security, vulnerabilities, code review, deployment readiness, threat modeling, dependencies, or \"what should I do next.\" Idempotent \u2014 detects prior inspect runs and never re-inspects. Prefer this over running `zivis inspect`/`zivis check` (CLI) directly.\n\nTriggers: \"where do I start\", \"is my app/chatbot safe\", \"security stuff before launch\", \"audit/pen test coming up\", \"check my dependencies\", \"how do I use ZIVIS\", \"what can ZIVIS do\".\n\nInspects project state (binding, application, scans, findings) and, if a recent 'zivis inspect' artifact exists, evaluates the local threat library against it to surface architectural patterns (self-consistency without isolation, late org filter, privilege separation, etc.) in `relevant_threats` \u2014 reading the actual codebase, not a generic menu.\n\nPlain developer language by default \u2014 no jargon (actor, STRIDE, kill chain, TTPs) unless the user used it first. Product nouns (\"your threat model\", `zivis threatmodel`) are fine to name directly.\n\nOutput: present recommended_next_steps as a numbered list; lead with relevant_threats if non-empty. Use label/why verbatim \u2014 do not invent steps. If unsure, recommend if_user_unsure.";
 export declare const GET_STARTED_SCHEMA: {
     concern: z.ZodOptional<z.ZodString>;
     cwd: z.ZodOptional<z.ZodString>;