@gpzhang2001/sharpkit-analysis 0.2.1

package/src/index.ts

@@ -0,0 +1,815 @@
+/**
+ * Analysis tools — port of strix tools/{threat_model,coverage,notes,
+ * thinking}/ + finish_scan: get/save/amend_threat_model (validated
+ * sections, size gates, append-only amendments), record/update/
+ * list_coverage (duplicate guard, evidence requirements, history),
+ * create/list/get/update/delete_note, think, and finish_scan (root-only,
+ * four required sections, coverage summary, final artifacts). State lives
+ * in per-scan mirror stores under the run dir (.state parity) and is
+ * provided as `pentestAnalysis` for the reporting package's coverage
+ * document and SARIF bridge.
+ * @module @gpzhang2001/sharpkit-analysis
+ */
+
+import { join } from 'node:path'
+import type { Context } from '@deepseek-ai/cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { JsonMirrorStore, generateId, normalizeTargetIdentity } from './stores.ts'
+
+export { normalizeTargetIdentity } from './stores.ts'
+
+/** Coverage outcome values (strix VALID_OUTCOMES). */
+export const VALID_OUTCOMES = ['reported', 'no_issue_found', 'ruled_out', 'not_applicable', 'needs_follow_up'] as const
+
+/** Outcomes that require evidence text (strix `_OUTCOMES_REQUIRING_EVIDENCE`). */
+const OUTCOMES_REQUIRING_EVIDENCE = new Set(['ruled_out', 'not_applicable', 'needs_follow_up'])
+
+/** Note categories (strix `_VALID_NOTE_CATEGORIES`). */
+export const VALID_NOTE_CATEGORIES = ['general', 'findings', 'methodology', 'questions', 'plan', 'wiki'] as const
+
+/** Required threat-model sections, matched as lowercase substrings (strix parity). */
+const REQUIRED_SECTIONS = ['overview', 'trust boundaries', 'attack surface', 'severity calibration'] as const
+
+/** Threat model gates (strix constants). */
+const MAX_MODEL_BYTES = 512 * 1024
+const MIN_MODEL_CHARS = 400
+const MIN_AMENDMENT_CHARS = 80
+const MAX_AMENDMENTS = 40
+
+/** Display timestamp in the coverage format. */
+function displayTimestamp(date: Date): string {
+  const pad = (value: number): string => String(value).padStart(2, '0')
+  return `${date.getUTCFullYear()}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())} ${pad(date.getUTCHours())}:${pad(date.getUTCMinutes())}:${pad(date.getUTCSeconds())} UTC`
+}
+
+/** Deployment-tunable configuration. */
+export interface Config {
+  /** Sandbox session cache key shared with the other tool packages. */
+  readonly scanId?: string
+  /** Scan targets (threat-model identity snapping). */
+  readonly scanTargets?: readonly string[]
+  /** Run directory for the .state mirrors (default sharpkit_runs/<scanId>/.state). */
+  readonly runDir?: string
+  /** Whether this composition's agent may call finish_scan (root guard). */
+  readonly allowFinish?: boolean
+}
+
+export const name = 'pentest-tool-analysis'
+
+export const inject = ['tools', 'pentestReporting']
+
+/** The per-scan analysis stores exposed to other packages. */
+export interface AnalysisHandle {
+  readonly coverage: JsonMirrorStore
+  readonly threatModels: JsonMirrorStore
+  readonly notes: JsonMirrorStore
+  /** Coverage entries in list order with ids (reporting package consumes). */
+  coverageEntries(): Array<Record<string, unknown> & { entry_id: string }>
+  outcomeCounts(): Record<string, number>
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    pentestAnalysis: AnalysisHandle
+  }
+}
+
+/** ISO-8601 timestamp (threat model + notes stores). */
+function isoNow(): string {
+  return new Date().toISOString().replace('Z', '+00:00')
+}
+
+export function apply(ctx: Context, config: Config = {}): AnalysisHandle {
+  const scanId = config.scanId ?? 'pentest'
+  const runDir = config.runDir ?? join('sharpkit_runs', scanId)
+  const stateDir = join(runDir, '.state')
+  const coverage = new JsonMirrorStore(join(stateDir, 'coverage.json'))
+  const threatModels = new JsonMirrorStore(join(stateDir, 'threat_models.json'))
+  const notes = new JsonMirrorStore(join(stateDir, 'notes.json'))
+  void coverage.hydrate()
+  void threatModels.hydrate()
+  void notes.hydrate()
+
+  const coverageEntries = (): Array<Record<string, unknown> & { entry_id: string }> =>
+    coverage.values().map(entry => ({ ...entry, entry_id: String(entry['id'] ?? '') })) as Array<Record<string, unknown> & { entry_id: string }>
+
+  const outcomeCounts = (): Record<string, number> => {
+    const counts: Record<string, number> = {}
+    for (const outcome of VALID_OUTCOMES) {
+      const count = coverage.values().filter(entry => entry['outcome'] === outcome).length
+      if (count > 0) counts[outcome] = count
+    }
+    return counts
+  }
+
+  const handle: AnalysisHandle = { coverage, threatModels, notes, coverageEntries, outcomeCounts }
+  ctx.provide('pentestAnalysis', handle)
+
+  const resolveTarget = (target: string | undefined): { readonly identity: string } | { readonly error: string } => {
+    const cleaned = target?.trim() ?? ''
+    if (cleaned === '') {
+      const targets = config.scanTargets ?? []
+      if (targets.length === 1) return { identity: normalizeTargetIdentity(targets[0] ?? '') }
+      return { error: 'target cannot be empty - name the target this threat model describes' }
+    }
+    return { identity: normalizeTargetIdentity(cleaned) }
+  }
+
+  ctx.tools.register(defineTool({
+    name: 'get_threat_model',
+    description: 'Fetch the threat model shared for a target in this scan (found=false when none exists yet). Read-only.',
+    parameters: {
+      target: { type: 'string', description: 'Target the model describes; omit when the scan has exactly one target.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          success: { type: 'boolean', required: true },
+          found: { type: 'boolean' },
+          target: { type: 'string' },
+          content: { type: 'string' },
+          amendments: { type: 'array', items: { type: 'object', properties: {}, additionalProperties: true } },
+          amendments_note: { type: 'string' },
+          message: { type: 'string' },
+          error: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+      render: (_args, value) => {
+        const result = value as { success: boolean; found?: boolean; error?: string }
+        if (!result.success) return [{ type: 'text', text: `get_threat_model failed: ${result.error ?? 'unknown'}` }]
+        return [{ type: 'text', text: result.found === true ? 'threat model found' : 'no threat model yet' }]
+      },
+    },
+    execute: (async (rawArgs: never) => {
+      const args = rawArgs as never as { target?: string }
+      const resolved = resolveTarget(args.target)
+      if ('error' in resolved) return { success: false, error: resolved.error }
+      const model = threatModels.get(resolved.identity)
+      if (model === undefined || String(model['content'] ?? '').trim() === '') {
+        return { success: true, found: false, target: resolved.identity, message: 'No threat model exists for this target yet. Save one with save_threat_model.' }
+      }
+      const amendments = model['amendments'] as unknown[] | undefined
+      return {
+        success: true,
+        found: true,
+        target: resolved.identity,
+        content: String(model['content']),
+        ...(amendments !== undefined && amendments.length > 0 ? { amendments, amendments_note: 'Addenda recorded by agents after the model was saved.' } : {}),
+      }
+    }) as never,
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'save_threat_model',
+    description: `Share your threat model for a target with the whole scan team (full replace; clears amendments). Must cover Overview, Trust Boundaries, Attack Surface, and Severity Calibration; minimum ${String(MIN_MODEL_CHARS)} characters, maximum 512KB.`,
+    parameters: {
+      target: { type: 'string', description: 'Target the model describes; omit when the scan has exactly one target.' },
+      content: { type: 'string', required: true, description: 'The full markdown threat model.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          success: { type: 'boolean', required: true },
+          target: { type: 'string' },
+          amendments_cleared: { type: 'integer' },
+          message: { type: 'string' },
+          error: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+      render: (_args, value) => {
+        const result = value as { success: boolean; error?: string }
+        return [{ type: 'text', text: result.success ? 'threat model saved' : `save_threat_model failed: ${result.error ?? 'unknown'}` }]
+      },
+    },
+    execute: (async (rawArgs: never) => {
+      const args = rawArgs as never as { target?: string; content: string }
+      const resolved = resolveTarget(args.target)
+      if ('error' in resolved) return { success: false, error: resolved.error }
+      const content = args.content.trim()
+      if (content.length < MIN_MODEL_CHARS) {
+        return { success: false, error: `Threat model is too thin (${String(content.length)} chars). It has to be usable by every agent in this scan.` }
+      }
+      if (Buffer.byteLength(content, 'utf8') > MAX_MODEL_BYTES) return { success: false, error: 'Threat model exceeds 512KB; tighten it.' }
+      const lower = content.toLowerCase()
+      const missing = REQUIRED_SECTIONS.filter(section => !lower.includes(section))
+      if (missing.length > 0) {
+        return { success: false, error: `Threat model is missing required section(s): ${missing.join(', ')}. Cover Overview, Trust Boundaries, Attack Surface, and Severity Calibration.` }
+      }
+      const previous = threatModels.get(resolved.identity)
+      const previousAmendments = previous?.['amendments']
+      const amendmentsCleared = Array.isArray(previousAmendments) ? previousAmendments.length : 0
+      threatModels.set(resolved.identity, {
+        target: resolved.identity,
+        written_at: isoNow(),
+        written_by: null,
+        content,
+      })
+      await threatModels.persist()
+      return {
+        success: true,
+        target: resolved.identity,
+        amendments_cleared: amendmentsCleared,
+        message: amendmentsCleared > 0
+          ? `Threat model shared with this scan. It replaced a previous model, folding ${String(amendmentsCleared)} amendment(s) into the full rewrite.`
+          : 'Threat model shared with this scan.',
+      }
+    }) as never,
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'amend_threat_model',
+    description: `Append an addendum to the existing threat model without rewriting it (minimum ${String(MIN_AMENDMENT_CHARS)} characters). Use save_threat_model for a full rewrite that folds amendments.`,
+    parameters: {
+      target: { type: 'string', description: 'Target the model describes; omit when the scan has exactly one target.' },
+      addendum: { type: 'string', required: true, description: 'The markdown addendum.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          success: { type: 'boolean', required: true },
+          target: { type: 'string' },
+          amendment_count: { type: 'integer' },
+          message: { type: 'string' },
+          error: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+      render: (_args, value) => {
+        const result = value as { success: boolean; error?: string }
+        return [{ type: 'text', text: result.success ? 'amendment recorded' : `amend_threat_model failed: ${result.error ?? 'unknown'}` }]
+      },
+    },
+    execute: (async (rawArgs: never) => {
+      const args = rawArgs as never as { target?: string; addendum: string }
+      const resolved = resolveTarget(args.target)
+      if ('error' in resolved) return { success: false, error: resolved.error }
+      const addendum = args.addendum.trim()
+      if (addendum.length < MIN_AMENDMENT_CHARS) {
+        return { success: false, error: `Amendment is too thin (${String(addendum.length)} chars). Give the new knowledge in full.` }
+      }
+      const model = threatModels.get(resolved.identity)
+      if (model === undefined) return { success: false, error: 'No threat model exists for this target yet. Save the full model with save_threat_model first.' }
+      const amendments = (model['amendments'] as unknown[] | undefined) ?? []
+      if (amendments.length >= MAX_AMENDMENTS) {
+        return { success: false, error: `This threat model already carries ${String(amendments.length)} amendments. Fold them into a full save_threat_model rewrite.` }
+      }
+      if (Buffer.byteLength(String(model['content']) + addendum, 'utf8') > MAX_MODEL_BYTES) {
+        return { success: false, error: 'Combined threat model exceeds 512KB; fold amendments with save_threat_model.' }
+      }
+      amendments.push({ at: isoNow(), by: null, content: addendum })
+      model['amendments'] = amendments
+      await threatModels.persist()
+      return { success: true, target: resolved.identity, amendment_count: amendments.length, message: 'Amendment recorded. Every agent reading the threat model will see it.' }
+    }) as never,
+  }))
+
+  // ---- coverage ----
+
+  interface CoverageValidateInput {
+    readonly surface: string
+    readonly riskArea: string
+    readonly outcome: string
+    readonly evidence: string
+  }
+
+  /** strix coverage `_validate`: normalization + per-field errors. */
+  function validateCoverage(input: CoverageValidateInput): { readonly outcome: string } | { readonly errors: string[] } {
+    const errors: string[] = []
+    if (input.surface === '') errors.push('surface cannot be empty - name the endpoint, route, file, or component')
+    if (input.riskArea === '') errors.push('risk_area cannot be empty - name what you were testing for')
+    const outcome = input.outcome.trim().toLowerCase().replaceAll('-', '_').replaceAll(' ', '_')
+    if (!(VALID_OUTCOMES as readonly string[]).includes(outcome)) {
+      errors.push(`Invalid outcome: '${input.outcome}'. Must be one of: [${VALID_OUTCOMES.join(', ')}]`)
+    }
+    if (OUTCOMES_REQUIRING_EVIDENCE.has(outcome) && input.evidence === '') {
+      errors.push(`evidence is required for outcome '${outcome}' - name the specific control, response, or observation that justifies it`)
+    }
+    return errors.length > 0 ? { errors } : { outcome }
+  }
+
+  const findCoverageDuplicate = (surface: string, riskArea: string): Record<string, unknown> | undefined =>
+    coverage.values().find(entry => String(entry['surface']).toLowerCase() === surface.toLowerCase() && String(entry['risk_area']).toLowerCase() === riskArea.toLowerCase())
+
+  ctx.tools.register(defineTool({
+    name: 'record_coverage',
+    description: "Record that you exercised an attack surface for a risk area, with an outcome. Outcomes: reported / no_issue_found / ruled_out / not_applicable / needs_follow_up. ruled_out, not_applicable, and needs_follow_up REQUIRE evidence. One entry per (surface, risk_area).",
+    parameters: {
+      surface: { type: 'string', required: true, description: 'The endpoint, route, file, or component you exercised.' },
+      risk_area: { type: 'string', required: true, description: 'What you were testing for (e.g. "SQL injection in login").' },
+      outcome: { type: 'string', required: true, enum: [...VALID_OUTCOMES], description: 'The testing outcome.' },
+      evidence: { type: 'string', description: 'Concrete observation justifying the outcome (required for some outcomes).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          success: { type: 'boolean', required: true },
+          entry_id: { type: 'string' },
+          outcome: { type: 'string' },
+          message: { type: 'string' },
+          error: { type: 'string' },
+          errors: { type: 'array', items: { type: 'string' } },
+          existing_entry_id: { type: 'string' },
+          existing_outcome: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+      render: (_args, value) => {
+        const result = value as { success: boolean; error?: string; errors?: string[] }
+        const reason = result.error ?? result.errors?.join('; ') ?? 'unknown'
+        return [{ type: 'text', text: result.success ? 'coverage recorded' : `record_coverage failed: ${reason}` }]
+      },
+    },
+    execute: (async (rawArgs: never) => {
+      const args = rawArgs as never as { surface?: string; risk_area?: string; outcome?: string; evidence?: string }
+      const surface = (args.surface ?? '').trim()
+      const riskArea = (args.risk_area ?? '').trim()
+      const evidence = (args.evidence ?? '').trim()
+      const checked = validateCoverage({ surface, riskArea, outcome: args.outcome ?? '', evidence })
+      if ('errors' in checked) return { success: false, error: 'Validation failed', errors: checked.errors }
+      const duplicate = findCoverageDuplicate(surface, riskArea)
+      if (duplicate !== undefined) {
+        return {
+          success: false,
+          error: `'${surface}' (${riskArea}) already has coverage entry ${String(duplicate['id'])}, recorded by ${String(duplicate['agent_name'] ?? 'an agent')} as '${String(duplicate['outcome'])}'. Two rows for the same surface and risk area are never allowed; update_coverage to change the outcome.`,
+          existing_entry_id: String(duplicate['id']),
+          existing_outcome: String(duplicate['outcome']),
+        }
+      }
+      const id = generateId(new Set(coverage.values().map(entry => String(entry['id'] ?? ''))))
+      if (id === null) return { success: false, error: 'could not allocate a coverage entry id' }
+      coverage.set(id, {
+        id,
+        surface,
+        risk_area: riskArea,
+        outcome: checked.outcome,
+        created_at: displayTimestamp(new Date()),
+        ...(evidence !== '' ? { evidence } : {}),
+      })
+      await coverage.persist()
+      return { success: true, entry_id: id, outcome: checked.outcome, message: `Coverage recorded for '${surface}' (${checked.outcome})` }
+    }) as never,
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'update_coverage',
+    description: "Move an existing coverage entry to a new outcome (surface and risk_area are never editable). The previous state is kept as history.",
+    parameters: {
+      entry_id: { type: 'string', required: true, description: 'Id from record_coverage or list_coverage.' },
+      outcome: { type: 'string', required: true, enum: [...VALID_OUTCOMES], description: 'The new outcome.' },
+      evidence: { type: 'string', description: 'Evidence for the new outcome (required for some outcomes).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          success: { type: 'boolean', required: true },
+          entry_id: { type: 'string' },
+          previous_outcome: { type: 'string' },
+          outcome: { type: 'string' },
+          message: { type: 'string' },
+          error: { type: 'string' },
+          errors: { type: 'array', items: { type: 'string' } },
+        },
+        additionalProperties: false,
+      },
+      render: (_args, value) => {
+        const result = value as { success: boolean; error?: string; errors?: string[] }
+        const reason = result.error ?? result.errors?.join('; ') ?? 'unknown'
+        return [{ type: 'text', text: result.success ? 'coverage updated' : `update_coverage failed: ${reason}` }]
+      },
+    },
+    execute: (async (rawArgs: never) => {
+      const args = rawArgs as never as { entry_id?: string; outcome?: string; evidence?: string }
+      const entryId = (args.entry_id ?? '').trim()
+      const entry = coverage.get(entryId)
+      if (entry === undefined) return { success: false, error: `No coverage entry '${entryId}'. Call list_coverage to see recorded entries.` }
+      const surface = String(entry['surface'] ?? '')
+      const riskArea = String(entry['risk_area'] ?? '')
+      const evidence = (args.evidence ?? '').trim()
+      const checked = validateCoverage({ surface, riskArea, outcome: args.outcome ?? '', evidence })
+      if ('errors' in checked) return { success: false, error: 'Validation failed', errors: checked.errors }
+      const previousOutcome = String(entry['outcome'])
+      const history = (entry['history'] as Array<Record<string, unknown>> | undefined) ?? []
+      const prior: Record<string, unknown> = { outcome: previousOutcome, recorded_at: String(entry['created_at']) }
+      if (entry['evidence'] !== undefined) prior['evidence'] = entry['evidence']
+      history.push(prior)
+      entry['history'] = history
+      entry['outcome'] = checked.outcome
+      entry['updated_at'] = displayTimestamp(new Date())
+      if (evidence !== '') entry['evidence'] = evidence
+      await coverage.persist()
+      return {
+        success: true,
+        entry_id: entryId,
+        previous_outcome: previousOutcome,
+        outcome: checked.outcome,
+        message: `'${surface}' (${riskArea}) moved from ${previousOutcome} to ${checked.outcome}. The previous state is kept as history.`,
+      }
+    }) as never,
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'list_coverage',
+    description: 'List coverage entries recorded in this scan (filters compose; outcome counts are over all entries).',
+    parameters: {
+      outcome: { type: 'string', description: 'Filter to one outcome.' },
+      surface: { type: 'string', description: 'Case-insensitive substring match on the surface.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          success: { type: 'boolean', required: true },
+          entries: { type: 'array', items: { type: 'object', properties: {}, additionalProperties: true }, required: true },
+          filtered_count: { type: 'integer', required: true },
+          total_count: { type: 'integer', required: true },
+          outcome_counts: { type: 'object', properties: {}, additionalProperties: true, required: true },
+          error: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+      render: (_args, value) => {
+        const result = value as { entries?: unknown[]; error?: string }
+        if (result.error !== undefined) return [{ type: 'text', text: `list_coverage failed: ${result.error}` }]
+        return [{ type: 'text', text: `${String(result.entries?.length ?? 0)} coverage entry(ies)` }]
+      },
+    },
+    execute: (async (rawArgs: never) => {
+      const args = rawArgs as never as { outcome?: string; surface?: string }
+      let outcomeFilter: string | undefined
+      if (args.outcome !== undefined && args.outcome !== '') {
+        outcomeFilter = args.outcome.trim().toLowerCase().replaceAll('-', '_').replaceAll(' ', '_')
+        if (outcomeFilter !== undefined && !(VALID_OUTCOMES as readonly string[]).includes(outcomeFilter)) {
+          return {
+            success: false,
+            error: `Invalid outcome: '${args.outcome}'. Must be one of: [${VALID_OUTCOMES.join(', ')}]`,
+            entries: [],
+            filtered_count: 0,
+            total_count: coverage.size,
+            outcome_counts: {},
+          }
+        }
+      }
+      const surfaceFilter = args.surface?.toLowerCase() ?? ''
+      const entries = coverageEntries()
+        .filter(entry => (outcomeFilter === undefined || entry['outcome'] === outcomeFilter))
+        .filter(entry => surfaceFilter === '' || String(entry['surface']).toLowerCase().includes(surfaceFilter))
+        .sort((a, b) => String(a['created_at']).localeCompare(String(b['created_at'])))
+        .map(entry => {
+          const listing: Record<string, unknown> = {
+            entry_id: entry.entry_id,
+            surface: entry['surface'],
+            risk_area: entry['risk_area'],
+            outcome: entry['outcome'],
+            created_at: entry['created_at'],
+          }
+          const evidence = entry['evidence']
+          if (typeof evidence === 'string' && evidence !== '') {
+            listing['evidence'] = evidence.length > 240 ? `${evidence.slice(0, 240)}...` : evidence
+          }
+          const history = entry['history'] as Array<Record<string, unknown>> | undefined
+          if (history !== undefined && history.length > 0) {
+            listing['previous_outcomes'] = history.map(item => item['outcome'])
+          }
+          return listing
+        })
+      return {
+        success: true,
+        entries,
+        filtered_count: entries.length,
+        total_count: coverage.size,
+        outcome_counts: outcomeCounts(),
+      }
+    }) as never,
+  }))
+
+  // ---- notes ----
+
+  const noteList = (): Array<Record<string, unknown> & { id: string }> =>
+    notes.values().map(entry => ({ ...entry, id: String(entry['id'] ?? '') })) as Array<Record<string, unknown> & { id: string }>
+
+  ctx.tools.register(defineTool({
+    name: 'create_note',
+    description: 'Create a persistent note shared across the scan team (categories: general/findings/methodology/questions/plan/wiki).',
+    parameters: {
+      title: { type: 'string', required: true, description: 'Short note title.' },
+      content: { type: 'string', required: true, description: 'The note body.' },
+      category: { type: 'string', enum: [...VALID_NOTE_CATEGORIES], description: 'Note category (default general).' },
+      tags: { type: 'array', items: { type: 'string' }, description: 'Optional tags.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          success: { type: 'boolean', required: true },
+          note_id: { type: 'string' },
+          message: { type: 'string' },
+          total_count: { type: 'integer' },
+          error: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+      render: (_args, value) => {
+        const result = value as { success: boolean; error?: string }
+        return [{ type: 'text', text: result.success ? 'note created' : `create_note failed: ${result.error ?? 'unknown'}` }]
+      },
+    },
+    execute: (async (rawArgs: never) => {
+      const args = rawArgs as never as { title?: string; content?: string; category?: string; tags?: string[] }
+      const title = (args.title ?? '').trim()
+      const content = (args.content ?? '').trim()
+      const category = (args.category ?? 'general').trim()
+      if (title === '') return { success: false, error: 'Title cannot be empty' }
+      if (content === '') return { success: false, error: 'Content cannot be empty' }
+      if (!(VALID_NOTE_CATEGORIES as readonly string[]).includes(category)) {
+        return { success: false, error: `Invalid category. Must be one of: ${VALID_NOTE_CATEGORIES.join(', ')}` }
+      }
+      const id = generateId(new Set(noteList().map(note => note.id)))
+      if (id === null) return { success: false, error: 'could not allocate a note id' }
+      const now = isoNow()
+      notes.set(id, {
+        id,
+        title,
+        content,
+        category,
+        tags: args.tags ?? [],
+        created_at: now,
+        updated_at: now,
+      })
+      await notes.persist()
+      return { success: true, note_id: id, message: `Note '${title}' created successfully`, total_count: notes.size }
+    }) as never,
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'list_notes',
+    description: 'List notes (filters compose; newest first).',
+    parameters: {
+      category: { type: 'string', description: 'Exact category filter.' },
+      tags: { type: 'array', items: { type: 'string' }, description: 'ANY-match tag filter.' },
+      search: { type: 'string', description: 'Substring match on title or content.' },
+      include_content: { type: 'boolean', description: 'Full content instead of a 280-char preview.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          success: { type: 'boolean', required: true },
+          notes: { type: 'array', items: { type: 'object', properties: {}, additionalProperties: true }, required: true },
+          filtered_count: { type: 'integer', required: true },
+          total_count: { type: 'integer', required: true },
+        },
+        additionalProperties: false,
+      },
+      render: (_args, value) => {
+        const result = value as { notes?: unknown[] }
+        return [{ type: 'text', text: `${String(result.notes?.length ?? 0)} note(s)` }]
+      },
+    },
+    execute: (async (rawArgs: never) => {
+      const args = rawArgs as never as { category?: string; tags?: string[]; search?: string; include_content?: boolean }
+      const category = args.category?.trim() ?? ''
+      const search = args.search?.toLowerCase() ?? ''
+      const tags = args.tags ?? []
+      const entries = noteList()
+        .filter(note => category === '' || note['category'] === category)
+        .filter(note => tags.length === 0 || tags.some(tag => (note['tags'] as string[] | undefined)?.includes(tag) === true))
+        .filter(note => search === '' || String(note['title']).toLowerCase().includes(search) || String(note['content']).toLowerCase().includes(search))
+        .sort((a, b) => String(b['created_at']).localeCompare(String(a['created_at'])))
+        .map(note => {
+          const listing: Record<string, unknown> = {
+            note_id: note.id,
+            title: note['title'],
+            category: note['category'],
+            tags: note['tags'],
+            created_at: note['created_at'],
+            updated_at: note['updated_at'],
+          }
+          const content = String(note['content'] ?? '')
+          listing[args.include_content === true ? 'content' : 'content_preview'] = args.include_content === true ? content : content.length > 280 ? `${content.slice(0, 280)}...` : content
+          return listing
+        })
+      return { success: true, notes: entries, filtered_count: entries.length, total_count: notes.size }
+    }) as never,
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'get_note',
+    description: 'Fetch one note by id.',
+    parameters: {
+      note_id: { type: 'string', required: true, description: 'Note id from list_notes or create_note.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          success: { type: 'boolean', required: true },
+          note: { type: 'object', properties: {}, additionalProperties: true },
+          error: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+      render: (_args, value) => {
+        const result = value as { success: boolean; error?: string }
+        return [{ type: 'text', text: result.success ? 'note returned' : `get_note failed: ${result.error ?? 'unknown'}` }]
+      },
+    },
+    execute: (async (rawArgs: never) => {
+      const args = rawArgs as never as { note_id?: string }
+      const noteId = (args.note_id ?? '').trim()
+      if (noteId === '') return { success: false, error: 'Note ID cannot be empty' }
+      const note = notes.get(noteId)
+      if (note === undefined) return { success: false, error: `Note with ID '${noteId}' not found` }
+      return { success: true, note: { ...note, note_id: noteId } }
+    }) as never,
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'update_note',
+    description: 'Revise a note (only the fields you pass change; updated_at always bumps).',
+    parameters: {
+      note_id: { type: 'string', required: true, description: 'Note id.' },
+      title: { type: 'string', description: 'Replacement title.' },
+      content: { type: 'string', description: 'Replacement content.' },
+      tags: { type: 'array', items: { type: 'string' }, description: 'Replacement tags (full replace).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          success: { type: 'boolean', required: true },
+          note_id: { type: 'string' },
+          message: { type: 'string' },
+          total_count: { type: 'integer' },
+          error: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+      render: (_args, value) => {
+        const result = value as { success: boolean; error?: string }
+        return [{ type: 'text', text: result.success ? 'note updated' : `update_note failed: ${result.error ?? 'unknown'}` }]
+      },
+    },
+    execute: (async (rawArgs: never) => {
+      const args = rawArgs as never as { note_id?: string; title?: string; content?: string; tags?: string[] }
+      const noteId = (args.note_id ?? '').trim()
+      const note = notes.get(noteId)
+      if (note === undefined) return { success: false, error: `Note with ID '${noteId}' not found` }
+      if (args.title !== undefined && args.title.trim() === '') return { success: false, error: 'Title cannot be empty' }
+      if (args.content !== undefined && args.content.trim() === '') return { success: false, error: 'Content cannot be empty' }
+      if (args.title !== undefined) note['title'] = args.title.trim()
+      if (args.content !== undefined) note['content'] = args.content.trim()
+      if (args.tags !== undefined) note['tags'] = args.tags
+      note['updated_at'] = isoNow()
+      await notes.persist()
+      return { success: true, note_id: noteId, message: `Note '${String(note['title'])}' updated successfully`, total_count: notes.size }
+    }) as never,
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'delete_note',
+    description: 'Delete a note by id.',
+    parameters: {
+      note_id: { type: 'string', required: true, description: 'Note id.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          success: { type: 'boolean', required: true },
+          note_id: { type: 'string' },
+          message: { type: 'string' },
+          total_count: { type: 'integer' },
+          error: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+      render: (_args, value) => {
+        const result = value as { success: boolean; error?: string }
+        return [{ type: 'text', text: result.success ? 'note deleted' : `delete_note failed: ${result.error ?? 'unknown'}` }]
+      },
+    },
+    execute: (async (rawArgs: never) => {
+      const args = rawArgs as never as { note_id?: string }
+      const noteId = (args.note_id ?? '').trim()
+      const note = notes.get(noteId)
+      if (note === undefined) return { success: false, error: `Note with ID '${noteId}' not found` }
+      notes.delete(noteId)
+      await notes.persist()
+      return { success: true, note_id: noteId, message: `Note '${String(note['title'])}' deleted successfully`, total_count: notes.size }
+    }) as never,
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'think',
+    description: 'Record a private reasoning step (no storage; use notes for persistent knowledge).',
+    parameters: {
+      thought: { type: 'string', required: true, description: 'The reasoning step.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          success: { type: 'boolean', required: true },
+          message: { type: 'string' },
+          error: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+      render: (_args, value) => {
+        const result = value as { success: boolean; error?: string }
+        return [{ type: 'text', text: result.success ? 'recorded' : `think failed: ${result.error ?? 'unknown'}` }]
+      },
+    },
+    execute: (async (rawArgs: never) => {
+      const args = rawArgs as never as { thought?: string }
+      if ((args.thought ?? '').trim() === '') return { success: false, error: 'Thought cannot be empty' }
+      return { success: true, message: 'Thought recorded' }
+    }) as never,
+  }))
+
+  // ---- finish_scan ----
+
+  ctx.tools.register(defineTool({
+    name: 'finish_scan',
+    description: 'Complete the scan: validates the four report sections, records the coverage summary, writes the final artifacts, and marks the scan completed. Root agent only.',
+    parameters: {
+      executive_summary: { type: 'string', required: true, description: 'Non-technical summary for stakeholders.' },
+      methodology: { type: 'string', required: true, description: 'How the scan was conducted.' },
+      technical_analysis: { type: 'string', required: true, description: 'Technical findings analysis.' },
+      recommendations: { type: 'string', required: true, description: 'Prioritized remediation recommendations.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          success: { type: 'boolean', required: true },
+          scan_completed: { type: 'boolean' },
+          message: { type: 'string' },
+          vulnerabilities_found: { type: 'integer' },
+          coverage_recorded: { type: 'integer' },
+          coverage_outcomes: { type: 'object', properties: {}, additionalProperties: true },
+          coverage_warning: { type: 'string' },
+          unresolved_surfaces: { type: 'array', items: { type: 'object', properties: {}, additionalProperties: true } },
+          warning: { type: 'string' },
+          error: { type: 'string' },
+          errors: { type: 'array', items: { type: 'string' } },
+        },
+        additionalProperties: false,
+      },
+      render: (_args, value) => {
+        const result = value as { success: boolean; error?: string; errors?: string[] }
+        const reason = result.error ?? result.errors?.join('; ') ?? 'unknown'
+        return [{ type: 'text', text: result.success ? 'scan completed' : `finish_scan failed: ${reason}` }]
+      },
+    },
+    execute: (async (rawArgs: never) => {
+      const args = rawArgs as never as { executive_summary?: string; methodology?: string; technical_analysis?: string; recommendations?: string }
+      if (config.allowFinish === false) {
+        return { success: false, scan_completed: false, error: 'This tool can only be used by the root/main agent. If you are a subagent, use agent_finish instead' }
+      }
+      const sections = {
+        executiveSummary: (args.executive_summary ?? '').trim(),
+        methodology: (args.methodology ?? '').trim(),
+        technicalAnalysis: (args.technical_analysis ?? '').trim(),
+        recommendations: (args.recommendations ?? '').trim(),
+      }
+      const errors: string[] = []
+      if (sections.executiveSummary === '') errors.push('Executive summary cannot be empty')
+      if (sections.methodology === '') errors.push('Methodology cannot be empty')
+      if (sections.technicalAnalysis === '') errors.push('Technical analysis cannot be empty')
+      if (sections.recommendations === '') errors.push('Recommendations cannot be empty')
+      if (errors.length > 0) return { success: false, error: 'Validation failed', errors }
+      const summary: Record<string, unknown> = {
+        coverage_recorded: coverage.size,
+        coverage_outcomes: outcomeCounts(),
+      }
+      if (coverage.size === 0) {
+        summary['coverage_warning'] = 'No coverage was recorded for this scan. The report cannot state what was and was not tested; record coverage with record_coverage in future scans.'
+      } else {
+        const unresolved = coverageEntries()
+          .filter(entry => entry['outcome'] === 'needs_follow_up')
+          .map(entry => ({ surface: entry['surface'], risk_area: entry['risk_area'] }))
+        if (unresolved.length > 0) {
+          summary['coverage_warning'] = `${String(unresolved.length)} surface(s) still need follow-up; they are listed in unresolved_surfaces.`
+          summary['unresolved_surfaces'] = unresolved
+        }
+      }
+      const reporting = (ctx as unknown as { pentestReporting?: { finishScan(sections: { executiveSummary: string; methodology: string; technicalAnalysis: string; recommendations: string }, status?: string): Promise<void>; state: { vulnerabilityReports: unknown[] } } }).pentestReporting
+      if (reporting === undefined) {
+        return { success: true, scan_completed: true, message: 'Scan completed (not persisted)', warning: 'Results could not be persisted - report state unavailable', ...summary }
+      }
+      await reporting.finishScan(sections)
+      return { success: true, scan_completed: true, message: 'Scan completed successfully', vulnerabilities_found: reporting.state.vulnerabilityReports.length, ...summary }
+    }) as never,
+  }))
+
+  return handle
+}
+