solidity-argus 0.3.2 → 0.3.4

package/src/hooks/tool-tracking-hook.ts

@@ -1,7 +1,21 @@
+import { randomUUID } from "node:crypto"
+import type { EventSink } from "../features/persistent-state/event-sink"
+import type {
+  DropDiagnostic,
+  DropDiagnosticsCollector,
+  DropPolicy,
+} from "../shared/drop-diagnostics"
+import { createDropDiagnosticsCollector } from "../shared/drop-diagnostics"
+import { createLogger } from "../shared/logger"
+import { normalizeToCanonicalFinding } from "../state/adapters"
 import type { FindingStore } from "../state/finding-store"
 import { createFindingStore } from "../state/finding-store"
+import type { AuditEvent } from "../state/schemas"
+import { SCHEMA_VERSION } from "../state/schemas"
 import type { AuditState, FindingSeverity, FuzzCounterexample, SoloditResult } from "../state/types"
 
+const logger = createLogger()
+
 type ToolHookInput = {
   tool: string
   args: unknown
@@ -13,6 +27,13 @@ type ToolExecutionMetadata = {
   findingsCount: number
 }
 
+export type ToolTrackingOptions = {
+  getEventSink?: () => EventSink | null
+  getSessionId?: () => string
+  dropPolicy?: DropPolicy
+  onChildSessionDetected?: (parentSessionId: string, childSessionId: string) => void
+}
+
 const VALID_SEVERITIES: ReadonlySet<string> = new Set([
   "Critical",
   "High",
@@ -56,7 +77,90 @@ function toRecord(value: unknown): Record<string, unknown> | undefined {
   return undefined
 }
 
-function processSlitherResult(parsed: Record<string, unknown>, store: FindingStore): number {
+async function emitToSink(sink: EventSink, event: AuditEvent): Promise<void> {
+  try {
+    await sink.append(event)
+  } catch (error) {
+    logger.error(
+      `Failed to emit ${event.type} event to sink: ${error instanceof Error ? error.message : String(error)}`,
+    )
+  }
+}
+
+function buildEvent(
+  type: AuditEvent["type"],
+  runId: string,
+  sessionId: string,
+  toolCallId: string,
+  payload: unknown,
+): AuditEvent {
+  return {
+    type,
+    run_id: runId,
+    seq: 0,
+    session_id: sessionId,
+    tool_call_id: toolCallId,
+    source: "tool-tracking-hook",
+    schema_version: SCHEMA_VERSION,
+    timestamp: Date.now(),
+    payload,
+  }
+}
+
+/**
+ * Defensively parse a child session_id from a `task` tool result.
+ * The result may be JSON with a top-level or nested `session_id` field,
+ * or plain text with an embedded JSON fragment.
+ */
+function parseChildSessionId(result: string): string | null {
+  try {
+    const parsed = JSON.parse(result)
+    if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+      if (typeof parsed.session_id === "string" && parsed.session_id.length > 0) {
+        return parsed.session_id
+      }
+      if (
+        typeof parsed.result === "object" &&
+        parsed.result !== null &&
+        !Array.isArray(parsed.result) &&
+        typeof parsed.result.session_id === "string" &&
+        parsed.result.session_id.length > 0
+      ) {
+        return parsed.result.session_id
+      }
+    }
+  } catch {
+    const match = result.match(/"session_id"\s*:\s*"([^"]+)"/)
+    if (match?.[1]) {
+      return match[1]
+    }
+  }
+  return null
+}
+
+function identifyMissingFields(
+  finding: Record<string, unknown>,
+  requiredFields: readonly string[],
+): string[] {
+  const missing: string[] = []
+  for (const field of requiredFields) {
+    if (field === "lines") {
+      if (!toLines(finding.lines)) missing.push(field)
+    } else if (typeof finding[field] !== "string") {
+      missing.push(field)
+    }
+  }
+  return missing
+}
+
+const SLITHER_REQUIRED = ["check", "description", "file", "lines"] as const
+const PATTERN_REQUIRED = ["pattern", "description", "file", "lines"] as const
+
+function processSlitherResult(
+  parsed: Record<string, unknown>,
+  store: FindingStore,
+  diag: DropDiagnosticsCollector,
+): number {
   const findings = parsed.findings
   if (!Array.isArray(findings)) return 0
 
@@ -76,6 +180,12 @@ function processSlitherResult(parsed: Record<string, unknown>, store: FindingSto
       typeof file !== "string" ||
       !lines
     ) {
+      const missing = identifyMissingFields(finding, SLITHER_REQUIRED)
+      diag.error(
+        "MISSING_REQUIRED_FIELD",
+        `Slither finding skipped: missing ${missing.join(", ")}`,
+        missing[0],
+      )
       continue
     }
 
@@ -94,7 +204,11 @@ function processSlitherResult(parsed: Record<string, unknown>, store: FindingSto
   return count
 }
 
-function processPatternResult(parsed: Record<string, unknown>, store: FindingStore): number {
+function processPatternResult(
+  parsed: Record<string, unknown>,
+  store: FindingStore,
+  diag: DropDiagnosticsCollector,
+): number {
   const sources = parsed.sources
   if (!Array.isArray(sources)) return 0
 
@@ -121,6 +235,12 @@ function processPatternResult(parsed: Record<string, unknown>, store: FindingSto
         typeof file !== "string" ||
         !lines
       ) {
+        const missing = identifyMissingFields(match, PATTERN_REQUIRED)
+        diag.error(
+          "MISSING_REQUIRED_FIELD",
+          `Pattern finding skipped: missing ${missing.join(", ")}`,
+          missing[0],
+        )
         continue
       }
 
@@ -141,7 +261,6 @@ function processPatternResult(parsed: Record<string, unknown>, store: FindingSto
 }
 
 function processContractAnalyzerResult(parsed: Record<string, unknown>, state: AuditState): void {
-  // Handle direct ContractProfile format (actual tool output)
   if (typeof parsed.filePath === "string") {
     if (!state.contractsReviewed.includes(parsed.filePath)) {
       state.contractsReviewed.push(parsed.filePath)
@@ -149,7 +268,6 @@ function processContractAnalyzerResult(parsed: Record<string, unknown>, state: A
     return
   }
 
-  // Handle wrapped { contractProfile: { filePath } } format
   const profile = toRecord(parsed.contractProfile)
   if (profile && typeof profile.filePath === "string") {
     if (!state.contractsReviewed.includes(profile.filePath)) {
@@ -220,19 +338,6 @@ function processSoloditResult(parsed: Record<string, unknown>, state: AuditState
   })
 }
 
-/**
- * Records a tool execution in the audit state.
- *
- * Multiple entries per tool name are allowed — if the same tool runs multiple times
- * (e.g., argus_slither_analyze on different targets), each execution is recorded
- * with its own findingsCount.
- *
- * Timing limitation: startTime and endTime are both set to Date.now() because this
- * hook fires in the tool.execute.after phase, after execution has already completed.
- * We cannot capture the actual start time. This is a known limitation of the hook
- * architecture. For accurate timing, the hook would need to fire in tool.execute.before
- * and tool.execute.after phases separately.
- */
 function recordToolExecution(state: AuditState, toolName: string, findingsCount: number): void {
   const now = Date.now()
   state.toolsExecuted.push({
@@ -244,18 +349,18 @@ function recordToolExecution(state: AuditState, toolName: string, findingsCount:
   })
 }
 
-/**
- * Creates a tool tracking hook that intercepts argus_* tool results
- * and updates audit state with extracted findings.
- *
- * Non-argus tools are ignored. Malformed JSON results are silently skipped.
- * Findings are deduplicated via the FindingStore (by check+file+lines).
- */
+export type ToolTrackingHook = {
+  (input: ToolHookInput): Promise<void>
+  getLastDiagnostics(): DropDiagnostic[]
+}
+
 export function createToolTrackingHook(
   getAuditState: () => AuditState | null,
   onStateChanged?: (metadata: ToolExecutionMetadata) => void,
-): (input: ToolHookInput) => Promise<void> {
+  options?: ToolTrackingOptions,
+): ToolTrackingHook {
   const storesByState = new WeakMap<AuditState, FindingStore>()
+  let lastDiagnostics: DropDiagnostic[] = []
 
   function resolveStateAndStore(): { state: AuditState; store: FindingStore } | null {
     const state = getAuditState()
@@ -270,19 +375,101 @@ export function createToolTrackingHook(
     return { state, store }
   }
 
-  return async (input: ToolHookInput): Promise<void> => {
+  const hookFn = async (input: ToolHookInput): Promise<void> => {
+    // Handle task tool (subagent dispatch) before argus_ filter
+    if (input.tool === "task") {
+      const childSessionId = parseChildSessionId(input.result)
+      const correlationId = randomUUID()
+      const resolved = resolveStateAndStore()
+      const sink = options?.getEventSink?.()
+      const sessionId = options?.getSessionId?.() ?? ""
+      const toolCallId = randomUUID()
+
+      if (childSessionId) {
+        options?.onChildSessionDetected?.(sessionId, childSessionId)
+      }
+
+      if (sink && resolved) {
+        const runId = resolved.state.sessionId
+        await emitToSink(
+          sink,
+          buildEvent("tool.started", runId, sessionId, toolCallId, {
+            tool: "task",
+            args: input.args,
+            correlation_id: correlationId,
+            child_session_id: childSessionId ?? null,
+          }),
+        )
+
+        await emitToSink(
+          sink,
+          buildEvent("tool.completed", runId, sessionId, toolCallId, {
+            tool: "task",
+            findingsCount: 0,
+            success: true,
+            correlation_id: correlationId,
+            child_session_id: childSessionId ?? null,
+          }),
+        )
+      }
+
+      if (resolved) {
+        recordToolExecution(resolved.state, "task", 0)
+        onStateChanged?.({ tool: "task", findingsCount: 0 })
+      }
+
+      return
+    }
+
     if (!input.tool.startsWith("argus_")) {
       return
     }
 
     const resolved = resolveStateAndStore()
-    if (!resolved) return
+    if (!resolved) {
+      const sinkForNoState = options?.getEventSink?.()
+      if (sinkForNoState) {
+        const toolCallId = randomUUID()
+        await emitToSink(
+          sinkForNoState,
+          buildEvent("tool.started", "", "", toolCallId, {
+            tool: input.tool,
+            args: input.args,
+          }),
+        )
+        await emitToSink(
+          sinkForNoState,
+          buildEvent("tool.completed", "", "", toolCallId, {
+            tool: input.tool,
+            findingsCount: 0,
+            success: false,
+          }),
+        )
+      }
+      return
+    }
 
     const { state: auditState, store } = resolved
+    const sink = options?.getEventSink?.()
+    const runId = auditState.sessionId
+    const sessionId = options?.getSessionId?.() ?? ""
+    const toolCallId = randomUUID()
+    const policy = options?.dropPolicy ?? "warn"
+    const diag = createDropDiagnosticsCollector(policy, "tool-tracking-hook", input.tool)
+
+    if (sink) {
+      await emitToSink(
+        sink,
+        buildEvent("tool.started", runId, sessionId, toolCallId, {
+          tool: input.tool,
+          args: input.args,
+        }),
+      )
+    }
+
+    const findingsCountBefore = auditState.findings.length
 
-    // Handle argus_skill_load first — it returns markdown, not JSON
     if (input.tool === "argus_skill_load") {
-      // Extract skill name from markdown header: "## Argus Skill: {name} [Source: ...]"
       const nameMatch = input.result.match(/^##\s+Argus Skill:\s+(.+?)(?:\s+\[|$)/m)
       const skillName = nameMatch?.[1]?.trim()
       if (skillName) {
@@ -293,6 +480,19 @@ export function createToolTrackingHook(
       }
       recordToolExecution(auditState, input.tool, 0)
       onStateChanged?.({ tool: input.tool, findingsCount: 0 })
+
+      if (sink) {
+        await emitToSink(
+          sink,
+          buildEvent("tool.completed", runId, sessionId, toolCallId, {
+            tool: input.tool,
+            findingsCount: 0,
+            success: true,
+          }),
+        )
+      }
+
+      lastDiagnostics = diag.getDiagnostics()
       return
     }
 
@@ -300,20 +500,26 @@ export function createToolTrackingHook(
     try {
       parsed = JSON.parse(input.result)
     } catch {
-      return // non-JSON tool output — nothing to track
+      diag.error("MALFORMED_JSON", `Failed to parse JSON result from ${input.tool}`)
+      lastDiagnostics = diag.getDiagnostics()
+      diag.throwIfStrict()
+      return
     }
 
     const record = toRecord(parsed)
-    if (!record) return
+    if (!record) {
+      lastDiagnostics = diag.getDiagnostics()
+      return
+    }
 
     let findingsCount = 0
 
     switch (input.tool) {
       case "argus_slither_analyze":
-        findingsCount = processSlitherResult(record, store)
+        findingsCount = processSlitherResult(record, store, diag)
         break
       case "argus_check_patterns":
-        findingsCount = processPatternResult(record, store)
+        findingsCount = processPatternResult(record, store, diag)
         break
       case "argus_analyze_contract":
         processContractAnalyzerResult(record, auditState)
@@ -386,7 +592,31 @@ export function createToolTrackingHook(
       }
     }
 
+    lastDiagnostics = diag.getDiagnostics()
+    diag.throwIfStrict()
+
     recordToolExecution(auditState, input.tool, findingsCount)
     onStateChanged?.({ tool: input.tool, findingsCount })
+
+    if (sink) {
+      const newFindings = auditState.findings.slice(findingsCountBefore)
+      for (const finding of newFindings) {
+        const { data: canonical } = normalizeToCanonicalFinding(finding, runId, 0)
+        await emitToSink(sink, buildEvent("finding.added", runId, sessionId, toolCallId, canonical))
+      }
+
+      await emitToSink(
+        sink,
+        buildEvent("tool.completed", runId, sessionId, toolCallId, {
+          tool: input.tool,
+          findingsCount,
+          success: true,
+        }),
+      )
+    }
   }
+
+  hookFn.getLastDiagnostics = (): DropDiagnostic[] => lastDiagnostics
+
+  return hookFn
 }

package/src/shared/audit-artifact-resolver.ts

@@ -0,0 +1,74 @@
+import { join } from "node:path"
+
+export class ArtifactResolverError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "ArtifactResolverError"
+  }
+}
+
+export interface AuditArtifactPaths {
+  /** {projectDir}/.opencode/argus-state.json (legacy compat) */
+  stateFile: string
+  /** {projectDir}/.opencode/runs/{runId}/events.jsonl */
+  journalFile: string
+  /** {projectDir}/.opencode/runs/{runId}/findings.json */
+  findingsFile: string
+  /** {projectDir}/.opencode/reports */
+  reportDir: string
+  /** {projectDir}/.opencode/runs/{runId}/evidence */
+  evidenceDir: string
+  /** {projectDir}/.opencode/archives */
+  archiveDir: string
+  /** {projectDir}/.opencode/runs/{runId} */
+  runDir: string
+}
+
+export interface AuditArtifactResolver {
+  readonly runId: string
+  readonly projectDir: string
+  paths(): AuditArtifactPaths
+  /** Returns {reportDir}/{filename} */
+  reportFilePath(filename: string): string
+  /** Returns {evidenceDir}/{filename} */
+  evidenceFilePath(filename: string): string
+}
+
+export function createAuditArtifactResolver(
+  runId: string,
+  projectDir: string,
+): AuditArtifactResolver {
+  if (!runId || runId.trim() === "") {
+    throw new ArtifactResolverError("runId must not be empty")
+  }
+  if (!projectDir || projectDir.trim() === "") {
+    throw new ArtifactResolverError("projectDir must not be empty")
+  }
+
+  const opencodeDir = join(projectDir, ".opencode")
+  const runDir = join(opencodeDir, "runs", runId)
+
+  const cachedPaths: AuditArtifactPaths = {
+    stateFile: join(opencodeDir, "argus-state.json"),
+    journalFile: join(runDir, "events.jsonl"),
+    findingsFile: join(runDir, "findings.json"),
+    reportDir: join(opencodeDir, "reports"),
+    evidenceDir: join(runDir, "evidence"),
+    archiveDir: join(opencodeDir, "archives"),
+    runDir,
+  }
+
+  return {
+    runId,
+    projectDir,
+    paths(): AuditArtifactPaths {
+      return cachedPaths
+    },
+    reportFilePath(filename: string): string {
+      return join(cachedPaths.reportDir, filename)
+    },
+    evidenceFilePath(filename: string): string {
+      return join(cachedPaths.evidenceDir, filename)
+    },
+  }
+}

package/src/shared/drop-diagnostics.ts

@@ -0,0 +1,108 @@
+import { createLogger } from "./logger"
+
+const logger = createLogger()
+
+/**
+ * "warn": log and continue (default). "error": collect, continue, surface.
+ * "strict-fail": collect, then throw after all diagnostics gathered.
+ */
+export type DropPolicy = "warn" | "error" | "strict-fail"
+
+export type DropReason = {
+  code: string
+  field?: string
+  message: string
+  policy: DropPolicy
+}
+
+export type DropDiagnostic = {
+  type: "drop"
+  source: string
+  tool?: string
+  reason: DropReason
+  timestamp: number
+}
+
+export type DropDiagnosticsCollector = {
+  warn(code: string, message: string, field?: string): void
+  error(code: string, message: string, field?: string): void
+  getDiagnostics(): DropDiagnostic[]
+  hasErrors(): boolean
+  throwIfStrict(): void
+}
+
+/** Thrown in strict-fail mode when error-level diagnostics exist. */
+export class DropDiagnosticsError extends Error {
+  public readonly diagnostics: DropDiagnostic[]
+
+  constructor(diagnostics: DropDiagnostic[]) {
+    const errorDiags = diagnostics.filter(
+      (d) => d.reason.policy === "strict-fail" || d.reason.policy === "error",
+    )
+    const summary = errorDiags.map((d) => `[${d.reason.code}] ${d.reason.message}`).join("; ")
+    super(`Drop diagnostics: ${errorDiags.length} error(s) — ${summary}`)
+    this.name = "DropDiagnosticsError"
+    this.diagnostics = diagnostics
+  }
+}
+
+export function createDropDiagnosticsCollector(
+  policy: DropPolicy,
+  source: string,
+  tool?: string,
+): DropDiagnosticsCollector {
+  const diagnostics: DropDiagnostic[] = []
+  let errorCount = 0
+
+  function push(code: string, message: string, level: "warn" | "error", field?: string): void {
+    const effectivePolicy: DropPolicy = level === "error" ? policy : "warn"
+    const diagnostic: DropDiagnostic = {
+      type: "drop",
+      source,
+      tool,
+      reason: {
+        code,
+        message,
+        policy: effectivePolicy,
+        ...(field !== undefined ? { field } : {}),
+      },
+      timestamp: Date.now(),
+    }
+    diagnostics.push(diagnostic)
+
+    if (level === "error") {
+      errorCount++
+    }
+
+    const logMsg = `[${source}${tool ? `:${tool}` : ""}] ${code}${field ? ` (field: ${field})` : ""}: ${message}`
+    if (level === "error") {
+      logger.warn(logMsg)
+    } else {
+      logger.info(logMsg)
+    }
+  }
+
+  return {
+    warn(code: string, message: string, field?: string): void {
+      push(code, message, "warn", field)
+    },
+
+    error(code: string, message: string, field?: string): void {
+      push(code, message, "error", field)
+    },
+
+    getDiagnostics(): DropDiagnostic[] {
+      return [...diagnostics]
+    },
+
+    hasErrors(): boolean {
+      return errorCount > 0
+    },
+
+    throwIfStrict(): void {
+      if (policy === "strict-fail" && errorCount > 0) {
+        throw new DropDiagnosticsError(diagnostics)
+      }
+    },
+  }
+}

package/src/shared/index.ts

@@ -9,3 +9,17 @@ export {
 export { stripJsoncComments } from "./jsonc-parser"
 export { createLogger, type Logger, type LoggerConfig } from "./logger"
 export { findFoundryProjectDir, resolveProjectDir } from "./project-utils"
+export {
+  ArtifactResolverError,
+  type AuditArtifactPaths,
+  type AuditArtifactResolver,
+  createAuditArtifactResolver,
+} from "./audit-artifact-resolver"
+export {
+  ReportPathError,
+  type ReportPathOptions,
+  type ResolvedReportPath,
+  formatReportDate,
+  sanitizeContractName,
+  resolveReportPath,
+} from "./report-path-resolver"

package/src/shared/report-path-resolver.ts

@@ -0,0 +1,70 @@
+import { join } from "node:path"
+
+export class ReportPathError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "ReportPathError"
+  }
+}
+
+export interface ReportPathOptions {
+  /** Contract name, e.g. "VulnerableVault" */
+  contractName: string
+  /** If not provided, use new Date() */
+  date?: Date
+  /** Canonical output directory (from config or default) */
+  outputDir: string
+  /** Optional run_id for run-scoped naming */
+  runId?: string
+}
+
+export interface ResolvedReportPath {
+  /** "VulnerableVault-security-audit-2026-02-21.md" */
+  filename: string
+  /** Full absolute path */
+  filePath: string
+  /** The directory used */
+  outputDir: string
+  /** runId if provided, else filename (deterministic identity) */
+  canonicalId: string
+}
+
+export function formatReportDate(date: Date): string {
+  const year = date.getFullYear()
+  const month = String(date.getMonth() + 1).padStart(2, "0")
+  const day = String(date.getDate()).padStart(2, "0")
+  return `${year}-${month}-${day}`
+}
+
+export function sanitizeContractName(name: string): string {
+  return name
+    .replace(/\s+/g, "-")
+    .replace(/[^a-zA-Z0-9-]/g, "")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "")
+}
+
+export function resolveReportPath(options: ReportPathOptions): ResolvedReportPath {
+  const { contractName, date, outputDir, runId } = options
+
+  if (!contractName || contractName.trim() === "") {
+    throw new ReportPathError("contractName must not be empty")
+  }
+  if (!outputDir || outputDir.trim() === "") {
+    throw new ReportPathError("outputDir must not be empty")
+  }
+
+  const resolvedDate = date ?? new Date()
+  const dateStr = formatReportDate(resolvedDate)
+  const sanitizedName = sanitizeContractName(contractName)
+  const filename = `${sanitizedName}-security-audit-${dateStr}.md`
+  const filePath = join(outputDir, filename)
+  const canonicalId = runId ?? filename
+
+  return {
+    filename,
+    filePath,
+    outputDir,
+    canonicalId,
+  }
+}