@gpzhang2001/sharpkit-reporting 0.2.1

package/src/index.ts

@@ -0,0 +1,1045 @@
+/**
+ * Vulnerability / dependency reporting tools — port of strix
+ * tools/reporting/tool.py: create_vulnerability_report,
+ * create_dependency_report, update_vulnerability_report, list_reports,
+ * get_report. Validation parity (runtime-validated value sets, CVSS
+ * computation, cross-class update guards), strix's exact response JSON
+ * shapes, and the artifacts fan-out on every mutation (md/csv/json/sarif +
+ * run.json last, atomic writes; SARIF always emitted even when empty).
+ * The dedupe LLM judge is a Config callback (deterministic dependency fast
+ * path runs regardless; judge failures default to not-duplicate).
+ * @module @gpzhang2001/sharpkit-reporting
+ */
+
+import { mkdir, readFile } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import type { Context } from '@deepseek-ai/cordis'
+import type Schema from '@deepseek-ai/schemastery'
+import z from '@deepseek-ai/schemastery'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { calculateCvss, dependencySeverity, validateCvssBreakdown, type CvssMetricName } from './cvss.ts'
+import { checkDuplicate, type DedupeJudge } from './dedupe.ts'
+import { ReportState, formatTimestamp, severityRank, type VulnerabilityReport } from './state.ts'
+import { renderVulnerabilityMd, writeCoverage, writeExecutiveReport, writeRunRecord, writeVulnerabilities } from './writers.ts'
+import { writeSarif, type SarifCoverage } from './sarif.ts'
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    pentestReporting: ReportingHandle
+  }
+}
+
+export { renderVulnerabilityMd }
+export { ReportState, cleanTitle, severityRank } from './state.ts'
+export { calculateCvss, cvssBaseScore, cvssSeverity, validateCvssBreakdown, dependencySeverity, buildCvssVector } from './cvss.ts'
+export { checkDuplicate, dependencyIdentity } from './dedupe.ts'
+export { buildSarif, sarifUri, ruleIdOf, classKeyword } from './sarif.ts'
+
+/** Deployment-tunable configuration. */
+export interface Config {
+  /** Run-name slug basis (strix derives it from the target label). */
+  readonly runName?: string
+  /** Runs root directory (sharpkit_runs; configurable back to strix_runs for legacy compat). */
+  readonly runsRoot?: string
+  /** Sandbox image version stamped into SARIF (tool.driver.version). */
+  readonly toolVersion?: string
+  /** Scan mode recorded into run.json. */
+  readonly scanMode?: string
+  /** Targets recorded into run.json. */
+  readonly targetsInfo?: readonly Record<string, unknown>[]
+  /** Pluggable dedupe LLM judge (dynamic findings; failures = not duplicate). */
+  readonly dedupeJudge?: DedupeJudge
+  /** File the CVSS-broad-CWE ban borrows from strix's guidance. */
+  readonly strictCwe?: boolean
+  /** Coverage document source (the analysis package wires itself in). */
+  readonly coverageSource?: CoverageSource
+  /** Auth mode recorded into run.json (strix codex.auth_mode; default "none"). */
+  readonly authMode?: string
+  /** Scan instruction recorded into run.json (strix set_scan_config). */
+  readonly instruction?: string
+  /** Diff scope recorded into run.json (diff-scope scans). */
+  readonly diffScope?: string
+  /** Non-interactive flag recorded into run.json. */
+  readonly nonInteractive?: boolean
+  /** Local source trees recorded into run.json. */
+  readonly localSources?: readonly Record<string, unknown>[]
+  /** Scope mode recorded into run.json (strix default "auto"). */
+  readonly scopeMode?: string
+  /** Diff base ref recorded into run.json (diff-scope scans). */
+  readonly diffBase?: string
+  /** MCP connection names recorded into run.json (strix record_mcp_connections). */
+  readonly mcpConnections?: readonly string[]
+}
+
+export const name = 'pentest-tool-reporting'
+
+export const inject = ['tools']
+
+export const Config: Schema<Config> = z.object({
+  runName: z.string(),
+  runsRoot: z.string().default('sharpkit_runs'),
+  toolVersion: z.string().default('0.1.0'),
+  scanMode: z.string().default('quick'),
+  targetsInfo: z.array(z.object({})),
+  strictCwe: z.boolean().default(true),
+  authMode: z.string().default('none'),
+  instruction: z.string(),
+  diffScope: z.string(),
+  nonInteractive: z.boolean(),
+  localSources: z.array(z.object({})),
+  scopeMode: z.string().default('auto'),
+  diffBase: z.string(),
+  mcpConnections: z.array(z.string()),
+}) as unknown as Schema<Config>
+
+/** strix-clean an optional string: literal null-words and empties → undefined. */
+function cleanOptional(value: string | undefined): string | undefined {
+  if (value === undefined) return undefined
+  const trimmed = value.trim()
+  if (trimmed === '' || /^(null|none|nil|undefined)$/i.test(trimmed)) return undefined
+  return trimmed
+}
+
+/** CVSS metric enum value sets (schema-level, matching strix runtime validation). */
+const CVSS_METRIC_SCHEMAS = {
+  attack_vector: { type: 'string' as const, required: true as const, enum: ['N', 'A', 'L', 'P'] } as const,
+  attack_complexity: { type: 'string' as const, required: true as const, enum: ['L', 'H'] },
+  privileges_required: { type: 'string' as const, required: true as const, enum: ['N', 'L', 'H'] },
+  user_interaction: { type: 'string' as const, required: true as const, enum: ['N', 'R'] },
+  scope: { type: 'string' as const, required: true as const, enum: ['U', 'C'] },
+  confidentiality: { type: 'string' as const, required: true as const, enum: ['N', 'L', 'H'] },
+  integrity: { type: 'string' as const, required: true as const, enum: ['N', 'L', 'H'] },
+  availability: { type: 'string' as const, required: true as const, enum: ['N', 'L', 'H'] },
+}
+
+const CODE_LOCATION_SCHEMA = {
+  type: 'object' as const,
+  properties: {
+    file: { type: 'string' as const, required: true as const },
+    start_line: { type: 'integer' as const, required: true as const },
+    end_line: { type: 'integer' as const, required: true as const },
+    snippet: { type: 'string' as const },
+    label: { type: 'string' as const },
+    fix_before: { type: 'string' as const },
+    fix_after: { type: 'string' as const },
+  },
+  additionalProperties: false,
+} as const
+
+/** Normalize + validate code_locations (tool.py `_normalize_code_locations`). */
+export function normalizeCodeLocations(raw: unknown): { readonly locations?: Record<string, unknown>[]; readonly errors: string[] } {
+  if (!Array.isArray(raw) || raw.length === 0) return { errors: [] }
+  const errors: string[] = []
+  const locations: Record<string, unknown>[] = []
+  for (const [index, item] of raw.entries()) {
+    if (typeof item !== 'object' || item === null) continue
+    const entry = item as Record<string, unknown>
+    const normalized: Record<string, unknown> = {}
+    const file = entry['file']
+    if (typeof file === 'string' && file !== '') normalized['file'] = file.trim()
+    const startLine = entry['start_line']
+    if (typeof startLine === 'number' && Number.isInteger(startLine)) normalized['start_line'] = startLine
+    else if (typeof startLine === 'string' && startLine !== '' && Number.isInteger(Number(startLine))) normalized['start_line'] = Number(startLine)
+    const endLine = entry['end_line']
+    if (typeof endLine === 'number' && Number.isInteger(endLine)) normalized['end_line'] = endLine
+    else if (typeof endLine === 'string' && endLine !== '' && Number.isInteger(Number(endLine))) normalized['end_line'] = Number(endLine)
+    for (const field of ['snippet', 'fix_before', 'fix_after'] as const) {
+      const value = entry[field]
+      if (typeof value === 'string' && value.trim() !== '') normalized[field] = value.replace(/^\n+|\n+$/g, '')
+    }
+    for (const field of ['label'] as const) {
+      const value = entry[field]
+      if (typeof value === 'string' && value.trim() !== '') normalized[field] = value.trim()
+    }
+    if (normalized['file'] === undefined || normalized['start_line'] === undefined) continue
+    if (typeof normalized['file'] === 'string' && (normalized['file'] as string).startsWith('/')) {
+      errors.push(`code_locations[${String(index)}]: file must be a repo-relative path (no leading '/')`)
+    }
+    if (typeof normalized['start_line'] !== 'number' || (normalized['start_line'] as number) < 1) {
+      errors.push(`code_locations[${String(index)}]: start_line must be an integer >= 1`)
+    }
+    if (normalized['end_line'] === undefined) {
+      errors.push(`code_locations[${String(index)}]: end_line is required`)
+    } else {
+      const start = normalized['start_line'] as number
+      const end = normalized['end_line'] as number
+      if (typeof end !== 'number' || end < 1) errors.push(`code_locations[${String(index)}]: end_line must be an integer >= 1`)
+      else if (end < start) errors.push(`code_locations[${String(index)}]: end_line (${String(end)}) must be >= start_line (${String(start)})`)
+    }
+    locations.push(normalized)
+  }
+  return { ...(locations.length > 0 ? { locations } : {}), errors }
+}
+
+/** CVE normalization (tool.py `_extract_cve` + `_validate_cve`). */
+export function normalizeCve(value: string | undefined): string | undefined {
+  const cleaned = cleanOptional(value)
+  if (cleaned === undefined) return undefined
+  const match = /CVE-\d{4}-\d{4,}/.exec(cleaned)
+  if (match === null) return undefined
+  return match[0]
+}
+
+/** CWE normalization (tool.py `_extract_cwe`). */
+export function normalizeCwe(value: string | undefined): string | undefined {
+  const cleaned = cleanOptional(value)
+  if (cleaned === undefined) return undefined
+  const match = /CWE-\d+/.exec(cleaned)
+  if (match === null) return undefined
+  return match[0]
+}
+
+/** Dependency metadata builder (tool.py `_build_dependency_metadata` order). */
+export function buildDependencyMetadata(fields: {
+  readonly packageName: string
+  readonly installedVersion: string
+  readonly advisoryCvss?: number | undefined
+  readonly packageEcosystem: string
+  readonly manifestPath: string
+  readonly fixedVersion?: string | undefined
+  readonly introducedBy?: string | undefined
+  readonly dependencyPath?: string | undefined
+  readonly reachability: string
+  readonly reachabilityEvidence?: string | undefined
+  readonly contextual?: {
+    readonly breakdown: Record<string, string>
+    readonly score: number
+    readonly vector: string
+    readonly reasoning: string
+  } | undefined
+}): Record<string, unknown> {
+  const metadata: Record<string, unknown> = {
+    package_name: fields.packageName,
+    installed_version: fields.installedVersion,
+  }
+  if (fields.advisoryCvss !== undefined) metadata['advisory_cvss'] = fields.advisoryCvss
+  metadata['package_ecosystem'] = fields.packageEcosystem
+  metadata['manifest_path'] = fields.manifestPath
+  if (fields.fixedVersion !== undefined) metadata['fixed_version'] = fields.fixedVersion
+  if (fields.introducedBy !== undefined) metadata['introduced_by'] = fields.introducedBy
+  if (fields.dependencyPath !== undefined) metadata['dependency_path'] = fields.dependencyPath
+  metadata['reachability'] = fields.reachability
+  if (fields.reachabilityEvidence !== undefined) metadata['reachability_evidence'] = fields.reachabilityEvidence
+  if (fields.contextual !== undefined) {
+    metadata['contextual_cvss_breakdown'] = fields.contextual.breakdown
+    metadata['contextual_cvss_score'] = fields.contextual.score
+    metadata['contextual_cvss_vector'] = fields.contextual.vector
+    metadata['contextual_cvss_reasoning'] = fields.contextual.reasoning.slice(0, 2000)
+  }
+  return metadata
+}
+
+/** Valid severities (strix `_VALID_SEVERITIES`). */
+const VALID_SEVERITIES = new Set(['critical', 'high', 'medium', 'low', 'info', 'none'])
+const VALID_FIX_EFFORT = new Set(['trivial', 'low', 'medium', 'high'])
+const VALID_CONFIDENCE = new Set(['high', 'medium', 'low'])
+const VALID_FINDING_CLASSES = new Set(['dynamic', 'dependency_cve'])
+const VALID_REACHABILITY = new Set(['not_imported', 'imported', 'vulnerable_symbol_used', 'reachable_call_path', 'unknown'])
+
+/** Broad CWEs strix's guidance forbids (tool.py docstring; enforced lightly). */
+const BROADCWES = new Set(['CWE-74', 'CWE-20', 'CWE-200', 'CWE-284', 'CWE-693'])
+
+/** Fields only a dynamic finding may carry on update (strix `_DYNAMIC_ONLY_UPDATE_FIELDS` inverse). */
+const DEPENDENCY_ONLY_UPDATE_FIELDS = new Set(['contextual_cvss_reasoning'])
+const DYNAMIC_ONLY_UPDATE_FIELDS = new Set(['endpoint', 'method', 'poc_description', 'poc_script_code'])
+
+export interface ReportingHandle {
+  readonly state: ReportState
+  readonly runDir: string
+  finishScan(sections: { readonly executiveSummary: string; readonly methodology: string; readonly technicalAnalysis: string; readonly recommendations: string }, status?: string): Promise<void>
+  writeNow(): Promise<void>
+  readRaw(relative: string): Promise<string>
+}
+
+/** Coverage document provider the analysis package supplies at wiring time. */
+export interface CoverageSource {
+  entries(): Array<Record<string, unknown>>
+  outcomeCounts(): Record<string, number>
+}
+
+/**
+ * Tool bodies are written with concrete arg/result types and bridged onto
+ * the DSL at registration (`as never`); the registry re-validates every
+ * call against the declared schema at the boundary.
+ */
+type ToolExecute = (args: never, exec: never) => Promise<never>
+
+interface ToolRunContextLike {
+  readonly signal: AbortSignal
+}
+
+interface CvssBreakdownArgs extends Record<CvssMetricName, string> {}
+
+interface CreateVulnArgs {
+  title: string
+  description: string
+  impact: string
+  target: string
+  technical_analysis: string
+  poc_description: string
+  poc_script_code: string
+  remediation_steps: string
+  evidence: string
+  assumptions: string
+  counterevidence: string
+  confidence: string
+  confidence_rationale?: string
+  severity_change_conditions: string
+  fix_effort: string
+  cvss_breakdown: CvssBreakdownArgs
+  endpoint?: string
+  method?: string
+  cve?: string
+  cwe?: string
+  code_locations?: Record<string, unknown>[]
+  fix_verification?: string
+  fix_pr_body?: string
+}
+
+interface UpdateArgs {
+  report_id: string
+  update_reason: string
+  title?: string
+  description?: string
+  impact?: string
+  target?: string
+  technical_analysis?: string
+  poc_description?: string
+  poc_script_code?: string
+  remediation_steps?: string
+  evidence?: string
+  assumptions?: string
+  counterevidence?: string
+  confidence?: string
+  confidence_rationale?: string
+  severity_change_conditions?: string
+  fix_effort?: string
+  cvss_breakdown?: CvssBreakdownArgs
+  endpoint?: string
+  method?: string
+  cve?: string
+  cwe?: string
+  code_locations?: Record<string, unknown>[]
+  fix_verification?: string
+  fix_pr_body?: string
+  contextual_cvss_reasoning?: string
+}
+
+interface CreateDepArgs {
+  title: string
+  description: string
+  target: string
+  cve: string
+  package_name: string
+  installed_version: string
+  advisory_cvss: number
+  impact: string
+  remediation_steps: string
+  assumptions: string
+  package_ecosystem: string
+  manifest_path?: string
+  fixed_version?: string
+  cwe?: string
+  technical_analysis?: string
+  fix_effort?: string
+  introduced_by?: string
+  dependency_path?: string
+  reachability?: string
+  reachability_evidence?: string
+  contextual_cvss_breakdown?: CvssBreakdownArgs
+  contextual_cvss_reasoning?: string
+}
+
+interface ListArgs {
+  severity?: string
+  finding_class?: string
+  target?: string
+  search?: string
+  include_details?: boolean
+}
+
+interface GetArgs {
+  report_id: string
+}
+
+export function apply(ctx: Context, config: Config = {}): ReportingHandle {
+  const runsRoot = config.runsRoot ?? 'sharpkit_runs'
+  const runName = config.runName ?? `pentest-${Math.random().toString(16).slice(2, 6)}`
+  const runDir = resolve(join(resolve(runsRoot), runName))
+  const state = new ReportState({ runName })
+  const toolVersion = config.toolVersion ?? '0.1.0'
+  /** scan_results block, set by finishScan and appended to run.json. */
+  let scanResults: Record<string, unknown> | undefined
+
+  // llm_usage ledger: session assistant/message usage events are the only
+  // host-side token source (dsh emits no cost events). Counts every session
+  // in this host process — single-scan deployments are exact; concurrent
+  // scans in one host share the ledger (session log stays authoritative).
+  const usageLedger = { requests: 0, inputTokens: 0, outputTokens: 0, totalTokens: 0 }
+  void ctx.on('session/event', (_session: unknown, event: unknown) => {
+    const record = event as { type?: string; data?: { usage?: { inputTokens?: number; outputTokens?: number; totalTokens?: number } } }
+    if (record.type !== 'assistant/message') return
+    const usage = record.data?.usage
+    if (usage === undefined || usage === null) return
+    usageLedger.requests += 1
+    usageLedger.inputTokens += usage.inputTokens ?? 0
+    usageLedger.outputTokens += usage.outputTokens ?? 0
+    usageLedger.totalTokens += usage.totalTokens ?? (usage.inputTokens ?? 0) + (usage.outputTokens ?? 0)
+  })
+  const llmUsageRecord = (): Record<string, unknown> => ({
+    requests: usageLedger.requests,
+    input_tokens: usageLedger.inputTokens,
+    output_tokens: usageLedger.outputTokens,
+    total_tokens: usageLedger.totalTokens,
+    // dsh session events carry tokens only; cost stays null (parity deviation
+    // recorded in the manual — strix estimates cost via LiteLLM callbacks).
+    cost: null,
+    agents: [],
+  })
+
+  const ensureRunDir = async (): Promise<string> => {
+    await mkdir(runDir, { recursive: true })
+    return runDir
+  }
+
+  /** Resolve the coverage source: Config hook first, else the analysis package's service. */
+  const coverageSource = (): CoverageSource | undefined => {
+    if (config.coverageSource !== undefined) return config.coverageSource
+    const analysis = ctx.get('pentestAnalysis') as
+      | { coverageEntries(): Array<Record<string, unknown>>; outcomeCounts(): Record<string, number> }
+      | undefined
+    return analysis === undefined ? undefined : { entries: () => analysis.coverageEntries(), outcomeCounts: () => analysis.outcomeCounts() }
+  }
+
+  /** Assemble the coverage document (state.py `_coverage_document`, minus agent-graph gaps). */
+  const coverageDocument = (): Record<string, unknown> => {
+    const source = coverageSource()
+    const entries = source?.entries() ?? []
+    const outcomes = source?.outcomeCounts() ?? {}
+    return {
+      schema_version: 1,
+      generated_at: formatTimestamp(new Date()),
+      run_id: state.runId,
+      run_name: state.runName,
+      scope: { targets: config.targetsInfo ?? [], scan_mode: config.scanMode ?? null, scope_mode: null, diff_scope: null, instruction: '' },
+      summary: {
+        surfaces_reviewed: entries.length,
+        outcomes,
+        findings_filed: state.vulnerabilityReports.length,
+        gaps: entries.filter(entry => entry['outcome'] === 'needs_follow_up').length,
+      },
+      completeness: { complete: state.status === 'completed', scan_status: state.status, exit_reason: null, caveats: state.status === 'running' ? ['scan still running'] : [] },
+      entries: entries.map(entry => ({
+        surface: entry['surface'],
+        risk_area: entry['risk_area'],
+        outcome: entry['outcome'],
+        outcome_label: { reported: 'Finding reported', no_issue_found: 'No issue identified', ruled_out: 'Ruled out', not_applicable: 'Not applicable', needs_follow_up: 'Requires further review' }[String(entry['outcome'])] ?? String(entry['outcome']),
+        ...(entry['evidence'] !== undefined ? { evidence: entry['evidence'] } : {}),
+        recorded_by: entry['agent_name'] ?? null,
+        recorded_at: entry['created_at'],
+        ...(entry['updated_at'] !== undefined ? { updated_at: entry['updated_at'] } : {}),
+        previous_outcomes: (entry['history'] as Array<Record<string, unknown>> | undefined)?.map(item => item['outcome']) ?? [],
+        source: 'agent_reported',
+      })),
+      gaps: entries.filter(entry => entry['outcome'] === 'needs_follow_up').map(entry => ({
+        kind: 'needs_follow_up',
+        surface: entry['surface'],
+        risk_area: entry['risk_area'],
+        detail: `'${String(entry['surface'])}' (${String(entry['risk_area'])}) still needs follow-up.`,
+      })),
+    }
+  }
+
+  /** Full artifacts fan-out (state.py `_save_artifacts` order; run.json LAST). */
+  const saveArtifacts = async (): Promise<void> => {
+    try {
+      const dir = await ensureRunDir()
+      const coverage = coverageDocument()
+      await writeCoverage(dir, coverage)
+      await writeVulnerabilities(dir, state.vulnerabilityReports, state.savedVulnIds)
+      const source = coverageSource()
+      const sarifCoverage: SarifCoverage | undefined = source === undefined ? undefined : { entries: coverage['entries'] as unknown as SarifCoverage['entries'], completeness: coverage['completeness'] as unknown as SarifCoverage['completeness'] }
+      await writeSarif(dir, state.vulnerabilityReports, { toolVersion, coverage: sarifCoverage })
+      // Key order follows strix's run_record construction (state.py :207-216
+      // initial fields, :612-631 set_scan_config appends, :560-582 scan_results).
+      const runRecord: Record<string, unknown> = {
+        run_id: state.runId,
+        run_name: state.runName,
+        start_time: state.startTime,
+        end_time: state.endTime,
+        status: state.status,
+        auth_mode: config.authMode ?? 'none',
+        targets_info: config.targetsInfo ?? [],
+        llm_usage: llmUsageRecord(),
+        instruction: config.instruction ?? null,
+        scan_mode: config.scanMode ?? 'quick',
+        diff_scope: config.diffScope ?? null,
+        non_interactive: config.nonInteractive ?? false,
+        local_sources: config.localSources ?? [],
+        scope_mode: config.scopeMode ?? 'auto',
+        diff_base: config.diffBase ?? null,
+      }
+      if (config.mcpConnections !== undefined && config.mcpConnections.length > 0) {
+        runRecord['mcp_connections'] = config.mcpConnections
+      }
+      if (scanResults !== undefined) runRecord['scan_results'] = scanResults
+      await writeRunRecord(dir, runRecord)
+    } catch (error) {
+      // Best-effort persistence surface (strix swallows OSError/RuntimeError)
+      // but said out loud: a silent artifact failure hides lost findings.
+      ctx.logger.warn(`pentest-reporting: artifact save failed: ${String(error instanceof Error ? error.message : error)}`)
+    }
+  }
+
+  /** The create-side validation + dedupe + persistence shared by both create tools. */
+  const persistCreate = async (
+    input: { readonly title: string; readonly severity: string; readonly findingClass: string; readonly dependencyMetadata?: Record<string, unknown>; readonly fields: Record<string, unknown> },
+    dedupeCandidate: Record<string, unknown>,
+  ): Promise<Record<string, unknown>> => {
+    const verdict = await checkDuplicate(dedupeCandidate, input.dependencyMetadata, state.vulnerabilityReports, config.dedupeJudge)
+    if (verdict.isDuplicate) {
+      const existing = state.vulnerabilityReports.find(report => report.id === verdict.duplicateId)
+      const title = existing?.title ?? ''
+      return {
+        success: false,
+        error: `Potential duplicate of '${title}' (id=${verdict.duplicateId.slice(0, 8)}...) — do not re-report the same vulnerability`,
+        duplicate_of: verdict.duplicateId,
+        confidence: verdict.confidence,
+        reason: verdict.reason,
+      }
+    }
+    try {
+      const report = state.addVulnerabilityReport(input)
+      await saveArtifacts()
+      return {
+        success: true,
+        message: `${input.findingClass === 'dependency_cve' ? 'Dependency finding' : 'Vulnerability report'} '${input.title}' created successfully`,
+        report_id: report.id,
+        severity: report.severity,
+        ...(report.cvss !== undefined ? { cvss_score: report.cvss } : {}),
+        ...(input.findingClass === 'dependency_cve' && report.cve !== undefined ? { cve: report.cve } : {}),
+      }
+    } catch (error) {
+      return { success: false, error: `Failed to create ${input.findingClass === 'dependency_cve' ? 'dependency' : 'vulnerability'} report: ${String(error instanceof Error ? error.message : error)}` }
+    }
+  }
+
+  ctx.tools.register(defineTool({
+    name: 'create_vulnerability_report',
+    description: "File a vulnerability report — one report per fully-verified finding, with a working PoC. Severity and CVSS are computed from the 8-metric cvss_breakdown you provide. On a duplicate verdict, revise the existing report via update_vulnerability_report instead of retrying. Never for known-CVE dependency findings — use create_dependency_report.",
+    parameters: {
+      title: { type: 'string', required: true, description: 'Specific finding title (e.g. "SQL Injection in /api/users login parameter").' },
+      description: { type: 'string', required: true, description: 'Concise, non-technical TL;DR (1-3 sentences).' },
+      impact: { type: 'string', required: true, description: 'The unauthorized result demonstrated by the PoC and its scope.' },
+      target: { type: 'string', required: true, description: 'Affected URL / domain / repository.' },
+      technical_analysis: { type: 'string', required: true, description: 'The mechanism and root cause.' },
+      poc_description: { type: 'string', required: true, description: 'Step-by-step reproduction (steps only, no code).' },
+      poc_script_code: { type: 'string', required: true, description: 'Working PoC (Python preferred).' },
+      remediation_steps: { type: 'string', required: true, description: 'Specific, actionable fix (prose, no code).' },
+      evidence: { type: 'string', required: true, description: 'Concrete proof: request/response excerpts, observed behavior, tool output.' },
+      assumptions: { type: 'string', required: true, description: 'Assumptions/prerequisites that make this finding impactful.' },
+      counterevidence: { type: 'string', required: true, description: 'REQUIRED: the strongest case against this finding, after actively looking for it.' },
+      confidence: { type: 'string', required: true, enum: ['high', 'medium', 'low'], description: 'Calibrated confidence.' },
+      confidence_rationale: { type: 'string', description: 'Required when confidence is not high: name the specific gap.' },
+      severity_change_conditions: { type: 'string', required: true, description: 'One concrete sentence on what evidence would raise or lower severity.' },
+      fix_effort: { type: 'string', required: true, enum: ['trivial', 'low', 'medium', 'high'], description: 'Estimated fix effort.' },
+      cvss_breakdown: { type: 'object', required: true, properties: CVSS_METRIC_SCHEMAS, additionalProperties: false, description: 'All 8 CVSS v3.1 metrics; score and severity are computed from it.' },
+      endpoint: { type: 'string', description: 'API path / Git path (e.g. /api/login).' },
+      method: { type: 'string', description: 'HTTP method when relevant.' },
+      cve: { type: 'string', description: 'CVE-YYYY-NNNNN if certain, else omit.' },
+      cwe: { type: 'string', description: 'CWE-NNN (most specific child) if certain, else omit.' },
+      code_locations: { type: 'array', items: CODE_LOCATION_SCHEMA, description: 'White-box findings: file/start_line/end_line/snippet/label/fix_before/fix_after.' },
+      fix_verification: { type: 'string', description: 'Required whenever any code_locations entry carries fix_after: the 4 ordered verification gates.' },
+      fix_pr_body: { type: 'string', description: 'Optional markdown PR-description body proposing the fix.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          success: { type: 'boolean', required: true },
+          message: { type: 'string' },
+          report_id: { type: 'string' },
+          severity: { type: 'string' },
+          cvss_score: { type: 'number' },
+          error: { type: 'string' },
+          errors: { type: 'array', items: { type: 'string' } },
+          duplicate_of: { type: 'string' },
+          confidence: { type: 'number' },
+          reason: { type: 'string' },
+          warning: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+      render: (_args, value) => {
+        const result = value as { success: boolean; report_id?: string; severity?: string; cvss_score?: number; error?: string }
+        if (!result.success) return [{ type: 'text', text: `create_vulnerability_report failed: ${result.error ?? 'unknown'}` }]
+        return [{ type: 'text', text: `filed ${result.report_id} (${String(result.severity)}, CVSS ${String(result.cvss_score)})` }]
+      },
+      presentationMeta: (args: unknown, value: unknown) => findingPresentationMeta(args, value),
+    },
+    execute: (async (rawArgs: never, rawExec: never) => {
+      const args = rawArgs as never as CreateVulnArgs
+      const exec = rawExec as never as ToolRunContextLike
+      void exec
+      const errors: string[] = []
+      const breakdown = args.cvss_breakdown as unknown as Record<CvssMetricName, string>
+      errors.push(...validateCvssBreakdown(breakdown))
+      const confidence = args.confidence.toLowerCase()
+      if (!VALID_CONFIDENCE.has(confidence)) errors.push(`Invalid confidence: ${args.confidence}. Must be one of: [high, low, medium]`)
+      const fixEffort = args.fix_effort.toLowerCase()
+      if (!VALID_FIX_EFFORT.has(fixEffort)) errors.push(`Invalid fix_effort: ${args.fix_effort}. Must be one of: [high, low, medium, trivial]`)
+      const cve = normalizeCve(args.cve)
+      if (args.cve !== undefined && cve === undefined) errors.push(`Invalid cve: ${args.cve}. Must match CVE-YYYY-NNNNN`)
+      const cwe = normalizeCwe(args.cwe)
+      if (args.cwe !== undefined && cwe === undefined) errors.push(`Invalid cwe: ${args.cwe}. Must match CWE-NNN`)
+      if (cwe !== undefined && config.strictCwe === true && BROADCWES.has(cwe)) errors.push(`${cwe} is too broad — file the most specific child CWE`)
+      const locations = normalizeCodeLocations(args.code_locations)
+      errors.push(...locations.errors)
+      const hasFixAfter = locations.locations?.some(location => typeof location['fix_after'] === 'string' && location['fix_after'] !== '') ?? false
+      if (hasFixAfter && cleanOptional(args.fix_verification) === undefined) errors.push('fix_verification is required when any code_locations entry carries fix_after')
+      if (args.confidence !== 'high' && cleanOptional(args.confidence_rationale) === undefined) errors.push('confidence_rationale is required when confidence is not high')
+      if (errors.length > 0) return { success: false, error: 'Validation failed', errors }
+      let cvssScore: number | undefined
+      let severity: string | undefined
+      try {
+        const computed = calculateCvss(breakdown)
+        cvssScore = computed.score
+        severity = computed.severity
+      } catch (error) {
+        return { success: false, error: 'Validation failed', errors: [String(error instanceof Error ? error.message : error)] }
+      }
+      const fields: Record<string, unknown> = {
+        description: args.description, impact: args.impact, target: args.target,
+        technical_analysis: args.technical_analysis, poc_description: args.poc_description,
+        poc_script_code: args.poc_script_code, remediation_steps: args.remediation_steps,
+        evidence: args.evidence, assumptions: args.assumptions, counterevidence: args.counterevidence,
+        confidence, confidence_rationale: args.confidence_rationale,
+        severity_change_conditions: args.severity_change_conditions, fix_effort: fixEffort,
+        cvss: cvssScore, cvss_breakdown: breakdown,
+        endpoint: args.endpoint, method: args.method, cve, cwe,
+        code_locations: locations.locations, fix_verification: args.fix_verification, fix_pr_body: args.fix_pr_body,
+      }
+      return persistCreate({ title: args.title, severity, findingClass: 'dynamic', fields }, {
+        title: args.title, description: args.description, impact: args.impact, target: args.target,
+        technical_analysis: args.technical_analysis, poc_description: args.poc_description,
+        poc_script_code: args.poc_script_code, endpoint: args.endpoint, method: args.method,
+      })
+    }) as unknown as ToolExecute,
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'update_vulnerability_report',
+    description: "Revise a vulnerability report that is already filed, keeping its id. Pass only the fields to replace; create's reporting rules apply. cvss_breakdown replaces the whole vector (score + severity recomputed). Reports keep their id, author, and filing time; the revision is recorded as update history.",
+    parameters: {
+      report_id: { type: 'string', required: true, description: 'Id of the report to revise (format vuln-NNNN).' },
+      update_reason: { type: 'string', required: true, description: 'What you learned that the report does not yet carry (1-2 sentences).' },
+      title: { type: 'string' }, description: { type: 'string' }, impact: { type: 'string' },
+      target: { type: 'string' }, technical_analysis: { type: 'string' }, poc_description: { type: 'string' },
+      poc_script_code: { type: 'string' }, remediation_steps: { type: 'string' }, evidence: { type: 'string' },
+      assumptions: { type: 'string' }, counterevidence: { type: 'string' },
+      confidence: { type: 'string', enum: ['high', 'medium', 'low'] },
+      confidence_rationale: { type: 'string' }, severity_change_conditions: { type: 'string' },
+      fix_effort: { type: 'string', enum: ['trivial', 'low', 'medium', 'high'] },
+      cvss_breakdown: { type: 'object', properties: CVSS_METRIC_SCHEMAS, additionalProperties: false },
+      endpoint: { type: 'string' }, method: { type: 'string' }, cve: { type: 'string' }, cwe: { type: 'string' },
+      code_locations: { type: 'array', items: CODE_LOCATION_SCHEMA },
+      fix_verification: { type: 'string' }, fix_pr_body: { type: 'string' },
+      contextual_cvss_reasoning: { type: 'string', description: 'Dependency findings only: what you observed in this codebase justifying the contextual cvss_breakdown.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          success: { type: 'boolean', required: true },
+          action: { type: 'string' },
+          message: { type: 'string' },
+          report_id: { type: 'string' },
+          updated_fields: { type: 'array', items: { type: 'string' } },
+          severity: { type: 'string' },
+          cvss_score: { type: 'number' },
+          error: { type: 'string' },
+          errors: { type: 'array', items: { type: 'string' } },
+          finding_class: { type: 'string' },
+          rejected_fields: { type: 'array', items: { type: 'string' } },
+        },
+        additionalProperties: false,
+      },
+      render: (_args, value) => {
+        const result = value as { success: boolean; report_id?: string; error?: string }
+        if (!result.success) return [{ type: 'text', text: `update_vulnerability_report failed: ${result.error ?? 'unknown'}` }]
+        return [{ type: 'text', text: `revised ${result.report_id}` }]
+      },
+      presentationMeta: (args: unknown, value: unknown) => findingPresentationMeta(args, value),
+    },
+    execute: (async (rawArgs: never, rawExec: never) => {
+      const args = rawArgs as never as UpdateArgs
+      const exec = rawExec as never as ToolRunContextLike
+      void exec
+      const reportId = cleanOptional(args.report_id)
+      const reason = cleanOptional(args.update_reason)
+      if (reportId === undefined || reason === undefined) {
+        return { success: false, error: `${reportId === undefined ? 'report_id' : 'update_reason'} cannot be empty - name the report you are revising and state what you learned that it does not yet carry` }
+      }
+      const report = state.vulnerabilityReports.find(entry => entry.id === reportId)
+      if (report === undefined) return { success: false, error: `Report with id '${reportId}' not found`, report_id: reportId }
+      const changes: Record<string, unknown> = {}
+      for (const [key, value] of Object.entries(args)) {
+        if (key === 'report_id' || key === 'update_reason') continue
+        const cleaned = typeof value === 'string' ? cleanOptional(value) : value
+        if (cleaned === undefined) continue
+        changes[key] = cleaned
+      }
+      if (Object.keys(changes).length === 0) {
+        return { success: false, error: 'No fields to update - pass at least one field you want to replace', report_id: reportId }
+      }
+      // Cross-class guard (tool.py `_fit_revision_to_class`).
+      const findingClass = (typeof report.finding_class === 'string' ? report.finding_class : (report.dependency_metadata !== undefined ? 'dependency_cve' : 'dynamic')) as string
+      const rejected: string[] = []
+      if (findingClass === 'dependency_cve') {
+        for (const field of DYNAMIC_ONLY_UPDATE_FIELDS) {
+          if (changes[field] !== undefined) rejected.push(field)
+        }
+      } else {
+        for (const field of DEPENDENCY_ONLY_UPDATE_FIELDS) {
+          if (changes[field] !== undefined) rejected.push(field)
+        }
+      }
+      if (rejected.length > 0) {
+        return {
+          success: false,
+          error: `Report '${reportId}' is a ${findingClass} finding, so it cannot carry ${rejected.join(', ')}. File your proof as its own vulnerability report instead of writing it onto this one.`,
+          report_id: reportId,
+          finding_class: findingClass,
+          rejected_fields: rejected,
+        }
+      }
+      // Dependency re-rating: breakdown must carry contextual reasoning.
+      if (changes['cvss_breakdown'] !== undefined && findingClass === 'dependency_cve') {
+        if (changes['contextual_cvss_reasoning'] === undefined && report.dependency_metadata === undefined) {
+          return { success: false, error: 'Validation failed', errors: ['contextual_cvss_reasoning is required when re-rating a dependency finding'], report_id: reportId }
+        }
+        const errors = validateCvssBreakdown(changes['cvss_breakdown'] as Record<string, unknown>)
+        if (errors.length > 0) return { success: false, error: 'Validation failed', errors, report_id: reportId }
+        const computed = calculateCvss(changes['cvss_breakdown'] as Record<CvssMetricName, string>)
+        changes['cvss'] = computed.score
+        changes['severity'] = computed.severity
+      } else if (changes['cvss_breakdown'] !== undefined) {
+        const errors = validateCvssBreakdown(changes['cvss_breakdown'] as Record<string, unknown>)
+        if (errors.length > 0) return { success: false, error: 'Validation failed', errors, report_id: reportId }
+        const computed = calculateCvss(changes['cvss_breakdown'] as Record<CvssMetricName, string>)
+        changes['cvss'] = computed.score
+        changes['severity'] = computed.severity
+      }
+      const outcome = state.updateVulnerabilityReport(reportId, changes, reason)
+      if ('noop' in outcome) {
+        return { success: false, error: `Report '${reportId}' already says this - nothing in your update changes it`, report_id: reportId }
+      }
+      await saveArtifacts()
+      const updated = outcome.report
+      return {
+        success: true,
+        action: 'updated',
+        message: `Report '${reportId}' now carries your revision. Do not file it again.`,
+        report_id: reportId,
+        updated_fields: (updated['update_history'] as { fields: string[] }[] | undefined)?.at(-1)?.fields ?? [],
+        severity: updated.severity,
+        ...(updated.cvss !== undefined ? { cvss_score: updated.cvss as number } : {}),
+      }
+    }) as unknown as ToolExecute,
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'create_dependency_report',
+    description: "File a known-CVE dependency (SCA) finding — one report per CVE x package. For vulnerable third-party package versions pinned in a lockfile/manifest/SBOM; no live PoC needed. Severity comes from the contextual_cvss_breakdown when provided, else the advisory score. Never for dynamically-proven vulnerabilities — use create_vulnerability_report.",
+    parameters: {
+      title: { type: 'string', required: true, description: 'e.g. "CVE-2024-1234 in lodash 4.17.20 (prototype pollution)".' },
+      description: { type: 'string', required: true, description: 'What the CVE is and why the pinned version is affected.' },
+      target: { type: 'string', required: true, description: 'Affected repository / project / manifest.' },
+      cve: { type: 'string', required: true, description: 'CVE-YYYY-NNNNN — required and verified.' },
+      package_name: { type: 'string', required: true, description: 'Affected package name (e.g. lodash).' },
+      installed_version: { type: 'string', required: true, description: 'The version currently pinned/installed.' },
+      advisory_cvss: { type: 'number', required: true, description: 'Published advisory base score (0.0-10.0).' },
+      impact: { type: 'string', required: true, description: 'What the CVE enables; business risk in this context.' },
+      remediation_steps: { type: 'string', required: true, description: 'How to fix (usually upgrade to a fixed version).' },
+      assumptions: { type: 'string', required: true, description: 'Exploitability/reachability assumptions & confidence.' },
+      package_ecosystem: { type: 'string', required: true, description: 'e.g. npm / pypi / maven / go.' },
+      manifest_path: { type: 'string', description: 'Repo-relative lockfile/manifest path (required).' },
+      fixed_version: { type: 'string', description: 'First non-vulnerable version, if known.' },
+      cwe: { type: 'string', description: 'CWE-NNN (most specific) if certain.' },
+      technical_analysis: { type: 'string', description: 'Optional deeper mechanism/root-cause detail.' },
+      fix_effort: { type: 'string', enum: ['trivial', 'low', 'medium', 'high'], description: 'Default low.' },
+      introduced_by: { type: 'string', description: 'For a transitive dep, the direct dependency pulling it in (name@version).' },
+      dependency_path: { type: 'string', description: 'Resolution chain joined with " > ".' },
+      reachability: { type: 'string', enum: ['not_imported', 'imported', 'vulnerable_symbol_used', 'reachable_call_path', 'unknown'], description: 'Usage-evidence level (default unknown).' },
+      reachability_evidence: { type: 'string', description: 'Concrete proof for the level (required).' },
+      contextual_cvss_breakdown: { type: 'object', properties: CVSS_METRIC_SCHEMAS, additionalProperties: false, description: 'Full CVSS v3.1 rating of this CVE in this codebase (required).' },
+      contextual_cvss_reasoning: { type: 'string', description: '2-4 verifiable sentences with file:line hops (required).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          success: { type: 'boolean', required: true },
+          message: { type: 'string' },
+          report_id: { type: 'string' },
+          severity: { type: 'string' },
+          cve: { type: 'string' },
+          error: { type: 'string' },
+          errors: { type: 'array', items: { type: 'string' } },
+          duplicate_of: { type: 'string' },
+          confidence: { type: 'number' },
+          reason: { type: 'string' },
+          warning: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+      render: (_args, value) => {
+        const result = value as { success: boolean; report_id?: string; severity?: string; cve?: string; error?: string }
+        if (!result.success) return [{ type: 'text', text: `create_dependency_report failed: ${result.error ?? 'unknown'}` }]
+        return [{ type: 'text', text: `filed ${result.report_id} (${String(result.severity)}) for ${result.cve ?? 'CVE'}` }]
+      },
+      presentationMeta: (args: unknown, value: unknown) => findingPresentationMeta(args, value),
+    },
+    execute: (async (rawArgs: never, _rawExec: never) => {
+      const args = rawArgs as never as CreateDepArgs
+      const errors: string[] = []
+      const requireText = (value: string | undefined, name: string): string | undefined => {
+        const cleaned = cleanOptional(value)
+        if (cleaned === undefined) errors.push(`${name} cannot be empty`)
+        return cleaned
+      }
+      const packageName = requireText(args.package_name, 'package_name')
+      const installedVersion = requireText(args.installed_version, 'installed_version')
+      const packageEcosystem = requireText(args.package_ecosystem, 'package_ecosystem')
+      const manifestPath = requireText(args.manifest_path, 'manifest_path')
+      const reachabilityEvidence = requireText(args.reachability_evidence, 'reachability_evidence')
+      const contextualReasoning = requireText(args.contextual_cvss_reasoning, 'contextual_cvss_reasoning')
+      const cve = normalizeCve(args.cve)
+      if (cve === undefined) errors.push(`Invalid cve: ${String(args.cve)}. Must match CVE-YYYY-NNNNN`)
+      const cwe = normalizeCwe(args.cwe)
+      if (args.cwe !== undefined && cwe === undefined) errors.push(`Invalid cwe: ${args.cwe}. Must match CWE-NNN`)
+      const advisory = args.advisory_cvss
+      if (typeof advisory !== 'number' || Number.isNaN(advisory) || advisory < 0 || advisory > 10) errors.push(`Invalid advisory_cvss: ${String(advisory)}. Must be between 0.0 and 10.0`)
+      const reachability = (args.reachability ?? 'unknown').toLowerCase()
+      if (!VALID_REACHABILITY.has(reachability)) errors.push(`Invalid reachability: ${String(args.reachability)}. Must be one of: [imported, not_imported, reachable_call_path, unknown, vulnerable_symbol_used]`)
+      const fixEffort = (args.fix_effort ?? 'low').toLowerCase()
+      if (!VALID_FIX_EFFORT.has(fixEffort)) errors.push(`Invalid fix_effort: ${String(args.fix_effort)}. Must be one of: [high, low, medium, trivial]`)
+      if (manifestPath !== undefined && (manifestPath.startsWith('/') || manifestPath.includes('\\') || manifestPath.split('/').some(part => part === '' || part === '.' || part === '..'))) {
+        errors.push(`Invalid manifest_path: ${manifestPath}. Must be a repo-relative path without absolute or traversal segments`)
+      }
+      let contextual: Parameters<typeof buildDependencyMetadata>[0]['contextual'] | undefined
+      const hasContextualBreakdown = args.contextual_cvss_breakdown !== undefined
+      if (hasContextualBreakdown || contextualReasoning !== undefined) {
+        if (!hasContextualBreakdown) errors.push('contextual_cvss_breakdown is required when contextual_cvss_reasoning is given')
+        if (contextualReasoning === undefined) errors.push('contextual_cvss_reasoning is required when contextual_cvss_breakdown is given')
+        if (hasContextualBreakdown && contextualReasoning !== undefined) {
+          const breakdown = args.contextual_cvss_breakdown as unknown as Record<CvssMetricName, string>
+          errors.push(...validateCvssBreakdown(breakdown))
+          const computed = calculateCvss(breakdown)
+          contextual = { breakdown, score: computed.score, vector: computed.vector, reasoning: contextualReasoning }
+        }
+      }
+      if (errors.length > 0) return { success: false, error: 'Validation failed', errors }
+      const severity = contextual !== undefined
+        ? calculateCvss(contextual.breakdown as CvssBreakdownArgs).severity
+        : dependencySeverity(advisory)
+      const metadata = buildDependencyMetadata({
+        packageName: packageName as string,
+        installedVersion: installedVersion as string,
+        advisoryCvss: advisory,
+        packageEcosystem: packageEcosystem as string,
+        manifestPath: manifestPath as string,
+        fixedVersion: cleanOptional(args.fixed_version),
+        introducedBy: cleanOptional(args.introduced_by),
+        dependencyPath: cleanOptional(args.dependency_path),
+        reachability,
+        reachabilityEvidence,
+        contextual,
+      })
+      const fields: Record<string, unknown> = {
+        description: args.description, impact: args.impact, target: args.target,
+        technical_analysis: args.technical_analysis, remediation_steps: args.remediation_steps,
+        assumptions: args.assumptions, fix_effort: fixEffort,
+        cve, cwe,
+        cvss: contextual !== undefined ? contextual.score : advisory,
+      }
+      return persistCreate({ title: args.title, severity, findingClass: 'dependency_cve', dependencyMetadata: metadata, fields }, {
+        title: args.title, description: args.description, target: args.target, cve,
+        dependency_metadata: metadata, technical_analysis: args.technical_analysis,
+      })
+    }) as unknown as ToolExecute,
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'list_reports',
+    description: "List vulnerability reports filed so far in this scan — metadata-first. Read-only and shared across all agents. Filters compose (AND); compact entries by default, full bodies with include_details.",
+    parameters: {
+      severity: { type: 'string', enum: ['critical', 'high', 'medium', 'low', 'info', 'none'], description: 'Filter to one severity.' },
+      finding_class: { type: 'string', enum: ['dynamic', 'dependency_cve'], description: 'dynamic or dependency_cve.' },
+      target: { type: 'string', description: 'Substring match against target/endpoint.' },
+      search: { type: 'string', description: 'Substring match against title and description.' },
+      include_details: { type: 'boolean', description: 'Full report bodies instead of compact entries (default false).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          success: { type: 'boolean', required: true },
+          reports: { type: 'array', items: { type: 'object', properties: {}, additionalProperties: true } },
+          filtered_count: { type: 'integer', required: true },
+          total_count: { type: 'integer', required: true },
+          severity_counts: { type: 'object', properties: {}, additionalProperties: true, required: true },
+          warning: { type: 'string' },
+          error: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+      render: (_args, value) => {
+        const result = value as { reports: unknown[]; total_count: number }
+        return [{ type: 'text', text: `${String(result.reports.length)} of ${String(result.total_count)} report(s)` }]
+      },
+    },
+    execute: (async (rawArgs: never, rawExec: never) => {
+      const args = rawArgs as never as ListArgs
+      const exec = rawExec as never as ToolRunContextLike
+      void exec
+      const severityFilter = cleanOptional(args.severity)?.toLowerCase()
+      const classFilter = cleanOptional(args.finding_class)?.toLowerCase()
+      const targetFilter = cleanOptional(args.target)?.toLowerCase()
+      const searchFilter = cleanOptional(args.search)?.toLowerCase()
+      if (severityFilter !== undefined && !VALID_SEVERITIES.has(severityFilter)) {
+        return { success: false, reports: [], filtered_count: 0, total_count: 0, severity_counts: {}, error: `Invalid severity: ${severityFilter}. Must be one of: [critical, high, info, low, medium, none]` }
+      }
+      if (classFilter !== undefined && !VALID_FINDING_CLASSES.has(classFilter)) {
+        return { success: false, reports: [], filtered_count: 0, total_count: 0, severity_counts: {}, error: `Invalid finding_class: ${classFilter}. Must be one of: [dependency_cve, dynamic]` }
+      }
+      const severityCounts: Record<string, number> = {}
+      for (const report of state.vulnerabilityReports) {
+        const key = String(report.severity)
+        severityCounts[key] = (severityCounts[key] ?? 0) + 1
+      }
+      const filtered = state.vulnerabilityReports.filter(report => {
+        if (severityFilter !== undefined && report.severity !== severityFilter) return false
+        if (classFilter !== undefined && String(report.finding_class) !== classFilter) return false
+        if (targetFilter !== undefined) {
+          const target = String(report.target ?? '').toLowerCase()
+          const endpoint = String(report.endpoint ?? '').toLowerCase()
+          if (!target.includes(targetFilter) && !endpoint.includes(targetFilter)) return false
+        }
+        if (searchFilter !== undefined) {
+          const title = String(report.title ?? '').toLowerCase()
+          const description = String(report.description ?? '').toLowerCase()
+          if (!title.includes(searchFilter) && !description.includes(searchFilter)) return false
+        }
+        return true
+      })
+      filtered.sort((a, b) => severityRank(a.severity) - severityRank(b.severity) || a.id.localeCompare(b.id))
+      const entries = filtered.map(report => args.include_details === true ? { ...report as unknown as Record<string, unknown> } : summarize(report))
+      return {
+        success: true,
+        reports: entries,
+        filtered_count: filtered.length,
+        total_count: state.vulnerabilityReports.length,
+        severity_counts: severityCounts,
+      }
+    }) as unknown as ToolExecute,
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'get_report',
+    description: 'Fetch one vulnerability report by its id (e.g. vuln-0001). Read-only; use list_reports to find ids.',
+    parameters: {
+      report_id: { type: 'string', required: true, description: "Report id from list_reports or a create response (format 'vuln-NNNN')." },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          success: { type: 'boolean', required: true },
+          report: { type: 'object', properties: {}, additionalProperties: true },
+          error: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+      render: (_args, value) => {
+        const result = value as { success: boolean; report?: { id?: string } | null; error?: string }
+        if (!result.success) return [{ type: 'text', text: `get_report failed: ${result.error ?? 'unknown'}` }]
+        return [{ type: 'text', text: `report ${String(result.report?.id)}` }]
+      },
+    },
+    execute: (async (rawArgs: never, rawExec: never) => {
+      const args = rawArgs as never as GetArgs
+      const exec = rawExec as never as ToolRunContextLike
+      void exec
+      const reportId = cleanOptional(args.report_id)
+      if (reportId === undefined) return { success: false, error: 'report_id cannot be empty' }
+      const report = state.vulnerabilityReports.find(entry => entry.id === reportId)
+      if (report === undefined) return { success: false, error: `Report with id '${reportId}' not found` }
+      return { success: true, report: { ...report as unknown as Record<string, unknown> } }
+    }) as unknown as ToolExecute,
+  }))
+
+  /** Compact summary entry (tool.py `_to_report_summary_entry` field order). */
+  function summarize(report: VulnerabilityReport): Record<string, unknown> {
+    const record = report as unknown as Record<string, unknown>
+    const summary: Record<string, unknown> = {}
+    for (const field of ['id', 'title', 'severity', 'cvss', 'confidence', 'finding_class', 'cve', 'cwe', 'target', 'endpoint', 'method', 'fix_effort', 'agent_name', 'timestamp']) {
+      const value = record[field]
+      if (value !== null && value !== undefined && value !== '') summary[field] = value
+    }
+    const description = record['description']
+    if (typeof description === 'string' && description !== '') {
+      summary['description_preview'] = description.length > 280 ? `${description.slice(0, 280)}...` : description
+    }
+    return summary
+  }
+
+  /**
+   * Replay-safe toolview meta for finding cards (ui FindingRow consumes
+   * severity/report_id/title from `result.meta`). Pure over (args, value);
+   * undefined keys are omitted so the snapshot stays lossless JSON.
+   */
+  function findingPresentationMeta(args: unknown, value: unknown): Record<string, string> {
+    const meta: Record<string, string> = {}
+    const title = (args as { title?: string }).title
+    if (title !== undefined) meta['title'] = title
+    const severity = (value as { severity?: string }).severity
+    if (severity !== undefined) meta['severity'] = severity
+    const reportId = (value as { report_id?: string }).report_id
+    if (reportId !== undefined) meta['report_id'] = reportId
+    return meta
+  }
+
+  const composeFinalReport = (sections: { readonly executiveSummary: string; readonly methodology: string; readonly technicalAnalysis: string; readonly recommendations: string }): string =>
+    ['# Executive Summary', sections.executiveSummary, '', '# Methodology', sections.methodology, '', '# Technical Analysis', sections.technicalAnalysis, '', '# Recommendations', sections.recommendations].join('\n')
+
+  const handle: ReportingHandle = {
+    state,
+    runDir,
+    /** Mark the scan complete and write the final report + artifacts. */
+    async finishScan(sections: { readonly executiveSummary: string; readonly methodology: string; readonly technicalAnalysis: string; readonly recommendations: string }, status = 'completed'): Promise<void> {
+      state.finalScanResult = composeFinalReport(sections)
+      state.complete(status)
+      // strix `update_scan_final_fields` (finish tool → state.py :560-582).
+      scanResults = {
+        scan_completed: true,
+        executive_summary: sections.executiveSummary,
+        methodology: sections.methodology,
+        technical_analysis: sections.technicalAnalysis,
+        recommendations: sections.recommendations,
+        success: status === 'completed',
+      }
+      const dir = await ensureRunDir()
+      await writeExecutiveReport(dir, state.finalScanResult, formatTimestamp(new Date()))
+      await saveArtifacts()
+    },
+    /** Dump the current run.json record (golden/test helper). */
+    async writeNow(): Promise<void> {
+      await saveArtifacts()
+    },
+    readRaw: async (relative: string): Promise<string> => readFile(join(runDir, relative), 'utf8'),
+  }
+  ctx.provide('pentestReporting', handle)
+  return handle
+}
+