solidity-argus 0.3.0 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solidity-argus",
-  "version": "0.3.0",
+  "version": "0.3.3",
   "description": "Solidity smart contract security auditing plugin for OpenCode — 4 specialized agents, 12 tools (11 core + optional Solodit), and a curated vulnerability knowledge base",
   "keywords": [
     "solidity",
@@ -51,6 +51,7 @@
   },
   "dependencies": {
     "@opencode-ai/plugin": "^1.2.10",
+    "@solidity-parser/parser": "^0.20.2",
     "yaml": "^2.8.2",
     "zod": "^4.1.8"
   },

package/src/agents/argus-prompt.ts

@@ -225,6 +225,16 @@ Task(subagent_type="scribe", prompt="Generate the final audit report for Project
   \`\`\`
 - Wait for both to complete before synthesizing their results.
 
+## TASK COMPLETION TRACKING
+
+You must track which audit phases are complete to avoid redundant work and tool re-execution.
+
+- **Read the context**: At the start of each response, check the \`<argus-context>\` block injected by the system. It contains the current phase (Reconnaissance, Automated Scanning, Manual Review, etc.) and a list of completed phases.
+- **Skip completed phases**: If a phase is marked complete in the context, do NOT re-run it. Proceed directly to the next incomplete phase.
+- **Avoid tool re-execution**: If Slither, Forge, or Solodit results already appear in the \`Tools:\` section of the context, do not re-dispatch the same tool. Reference the existing results instead.
+- **Mark phase completion**: After completing a phase, explicitly state "Phase X complete" in your response before moving to the next phase. This signals to the system that the phase is done.
+- **Example flow**: If context shows "Reconnaissance: complete, Automated Scanning: complete", skip both and begin Manual Review. After Manual Review, state "Phase 3 (Manual Review) complete" before proceeding to Attack Surface Mapping.
+
 ## TOOL AWARENESS & USAGE
 
 Your subagents have access to these specialized tools. Know when to delegate each.

package/src/agents/pythia-prompt.ts

@@ -84,6 +84,16 @@ You have two primary tools. Master them.
 - Returns a list of matches with line numbers.
 - **Crucial**: You must verify the context. A regex match for \`selfdestruct\` is not a bug if it's in a test file or a legitimate upgrade mechanism (though still risky).
 
+## EMPTY RESULTS STRATEGY
+
+When \`argus_solodit_search\` returns zero results for a query:
+
+1.  **Retry with alternative keywords** (2-3 variations). Example: If "ERC4626 inflation" returns nothing, try "vault share manipulation" or "exchange rate attack".
+2.  **If still empty**, fall back to \`argus_check_patterns\` with relevant pattern categories (e.g., \`["access-control", "logic-error"]\`).
+3.  **Never report empty-handed**. Pattern-based findings are valid research output. Combine them with manual code review to provide actionable intelligence.
+
+This ensures Pythia always delivers research value, even when Solodit has no direct precedent.
+
 ## SKILLS SYSTEM
 
 OpenCode has a powerful **Skills** system that allows you to load specialized knowledge modules. The Argus knowledge base includes 75+ curated SKILL.md files, 13 YAML pattern packs, and 15 real-world exploit case studies covering $3B+ in losses.

package/src/agents/scribe-prompt.ts

@@ -8,7 +8,7 @@ Your core responsibilities are:
 1.  **Aggregation**: Collecting findings from various tools and subagents.
 2.  **Deduplication**: Merging similar findings (e.g., multiple Slither warnings for the same issue).
 3.  **Contextualization**: Explaining *why* a finding matters in the context of the specific protocol.
-4.  **Report Generation**: Producing the final Markdown artifact using \`argus_generate_report\`.
+4.  **Report Generation**: Producing the final Markdown artifact and writing it to disk.
 
 ## REPORT STRUCTURE
 
@@ -41,21 +41,13 @@ You must adhere to these strict writing standards:
 
 ## HOW TO GENERATE THE REPORT
 
-You have two approaches. Use whichever fits the input you receive from Argus.
+Argus passes you findings in natural language. Write the full report yourself in Markdown following the Report Structure above.
 
-### Approach 1: Use \`argus_generate_report\` tool
-If you have structured findings data, call the tool:
--   \`project_name\` (string): The name of the protocol or project.
--   \`scope\` (string[]): List of files or contracts that were audited.
--   \`include_executive_summary\` (boolean): Default \`true\`.
--   \`severity_threshold\` (string): "critical", "high", "medium", "low", or "informational". Usually "low" or "informational" to include everything.
--   \`audit_state\` (string): JSON string of findings. Format each finding as: \`{"id":"f1","check":"name","severity":"High","confidence":"High","description":"...","file":"Contract.sol","lines":[1,10],"source":"manual"}\`
-
-### Approach 2: Write the report directly as Markdown
-If Argus passes findings in natural language (which is common), write the full report yourself in Markdown following the Report Structure below. This is often faster and produces better results than trying to serialize findings into JSON for the tool.
-
-**Choose Approach 2 when**: Argus gives you a natural language list of findings, descriptions, and context. Just write the report.
-**Choose Approach 1 when**: You have structured JSON finding data ready to pass.
+**Your workflow**:
+1. Read the findings Argus provides. Deduplicate, cross-reference, and assess severity.
+2. Write the complete report in Markdown following the Report Structure and Output Format sections.
+3. Save the report to disk using the \`write\` tool. Path: \`.opencode/reports/{ProjectName}-audit-{YYYY-MM-DD}.md\` relative to the project root.
+4. Confirm the file path in your response to Argus: "Report written to: {filePath}".
 
 ## QUALITY STANDARDS
 

package/src/agents/sentinel-prompt.ts

@@ -31,8 +31,19 @@ You operate in a loop of **Scan -> Analyze -> Verify**.
     - Use \`argus_gas_analysis\` to identify gas-intensive functions that may indicate inefficient or vulnerable logic.
 
 4.  **Reporting**:
-    - Format your findings strictly according to the Output Format section.
-    - Report back to Argus with confirmed findings.
+     - Format your findings strictly according to the Output Format section.
+     - Report back to Argus with confirmed findings.
+
+## POC VERIFICATION
+
+After writing a Proof of Concept test to reproduce a suspected vulnerability:
+
+1.  **Always run \`argus_forge_test\`** on the PoC test file immediately after writing it.
+2.  **Report the result** to Argus: pass count, fail count, and any revert reasons.
+3.  **If the PoC fails** (test does not trigger the bug as expected), revise the test logic and retry. Do not assume the bug exists if the PoC cannot reproduce it.
+4.  **If the PoC passes**, the vulnerability is confirmed. Escalate to Argus with full details.
+
+This ensures every PoC is verified before reporting, eliminating false positives.
 
 ## TOOL USAGE GUIDE
 

package/src/config/schema.ts

@@ -31,6 +31,7 @@ const ReportingConfigSchema = z.object({
   format: z.enum(["markdown"]).default("markdown"),
   severityThreshold: z.enum(["critical", "high", "medium", "low", "informational"]).default("low"),
   gasAnalysis: z.boolean().default(false),
+  output_dir: z.string().default(".opencode/reports/"),
 })
 
 const SoloditConfigSchema = z.object({
@@ -69,6 +70,7 @@ export const ArgusConfigSchema = z.object({
     format: "markdown",
     severityThreshold: "low",
     gasAnalysis: false,
+    output_dir: ".opencode/reports/",
   }),
   solodit: SoloditConfigSchema.default({
     enabled: true,

package/src/create-hooks.ts

@@ -176,11 +176,16 @@ export function createHooks(args: {
       }
 
       if (type === "session.deleted") {
+        await debouncedSave.flush()
+        if (auditState) {
+          await auditStateManager.save(auditState)
+        }
+        await auditStateManager.archive()
+
         if (sessionId) {
           agentTracker.clearSession(sessionId)
         }
 
-        await auditStateManager.archive()
         runJournal.log({
           type: "session.deleted",
           timestamp: Date.now(),

package/src/hooks/system-prompt-hook.ts

@@ -3,6 +3,15 @@ import type { AuditState, FindingSeverity } from "../state/types"
 const DEFAULT_TOKEN_BUDGET = 2000
 const TOKENS_PER_CHAR = 4
 
+const TOOL_SHORT_NAMES: Record<string, string> = {
+  argus_slither_analyze: "slither",
+  argus_forge_test: "forge-test",
+  argus_check_patterns: "patterns",
+  argus_solodit_search: "solodit",
+  argus_analyze_contract: "analyzer",
+}
+const KEY_TOOLS = ["slither", "forge-test", "patterns", "solodit", "analyzer"]
+
 export interface SystemPromptHookDeps {
   getAuditState: () => AuditState | null
   getAgentForSession: (sessionID: string) => string | undefined
@@ -52,7 +61,13 @@ export function buildDynamicContext(
     severityCounts[finding.severity]++
   }
 
+  const executedToolNames = new Set(
+    auditState.toolsExecuted.map((t) => TOOL_SHORT_NAMES[t.tool] ?? t.tool),
+  )
   const tools = auditState.toolsExecuted.map((tool) => tool.tool).join(", ") || "none"
+  const taskStatus = KEY_TOOLS.map(
+    (t) => `${t}=${executedToolNames.has(t) ? "done" : "pending"}`,
+  ).join(" ")
   const unavailable = auditState.unavailableTools ?? []
   const lines: string[] = [
     `<argus-context agent="${agent}">`,
@@ -60,6 +75,7 @@ export function buildDynamicContext(
     `Contracts: ${auditState.contractsReviewed.length} reviewed`,
     `Findings: Critical=${severityCounts.Critical} High=${severityCounts.High} Medium=${severityCounts.Medium} Low=${severityCounts.Low} Info=${severityCounts.Informational}`,
     `Tools: ${tools}`,
+    `Tasks: ${taskStatus}`,
   ]
 
   if (unavailable.length > 0) {
@@ -72,9 +88,10 @@ export function buildDynamicContext(
   let summary = lines.join("\n")
 
   if (estimateTokens(summary) > tokenBudget) {
+    const doneCount = KEY_TOOLS.filter((t) => executedToolNames.has(t)).length
     summary = [
       `<argus-context agent="${agent}">`,
-      `Phase: ${auditState.currentPhase} | Findings: ${auditState.findings.length} | Contracts: ${auditState.contractsReviewed.length}`,
+      `Phase: ${auditState.currentPhase} | Findings: ${auditState.findings.length} | Contracts: ${auditState.contractsReviewed.length} | Tasks: ${doneCount}/${KEY_TOOLS.length} done`,
       "</argus-context>",
     ].join("\n")
   }

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

@@ -321,8 +321,13 @@ export function createToolTrackingHook(
       case "argus_solodit_search":
         processSoloditResult(record, auditState)
         break
-      case "argus_forge_test":
+      case "argus_forge_test": {
+        const summary = toRecord(record.summary)
+        if (summary && typeof summary.failed === "number") {
+          findingsCount = summary.failed
+        }
         break
+      }
       case "argus_forge_fuzz":
         processFuzzResult(record, auditState)
         break

package/src/index.ts

@@ -13,7 +13,7 @@ const ArgusPlugin: Plugin = async (ctx) => {
   const config = loadArgusConfig(projectDir)
 
   if (config.solodit?.enabled !== false) {
-    startSoloditMcp(config.solodit?.port ?? 3000)
+    await startSoloditMcp(config.solodit?.port ?? 3000)
   }
 
   const isHookEnabled = createHookGuard(config.disabled_hooks)

package/src/solodit-lifecycle.ts

@@ -182,21 +182,22 @@ export async function startSoloditMcp(port: number): Promise<void> {
   soloditChild = spawnSoloditChild(port)
   trackChildExit(soloditChild)
 
-  ;(async () => {
-    const delays = [2000, 4000, 8000]
-    for (const delay of delays) {
-      await Bun.sleep(delay)
-      const health = await checkSoloditHealth(port, true)
-      if (health.reachable) {
-        soloditAvailable = true
-        logger.debug(`Solodit MCP healthy on port ${port}`)
-        return
-      }
+  const deadline = AbortSignal.timeout(5000)
+  const delays = [1000, 2000]
+  for (const delay of delays) {
+    if (deadline.aborted) break
+    await Bun.sleep(delay)
+    if (deadline.aborted) break
+    const healthResult = await checkSoloditHealth(port, true)
+    if (healthResult.reachable) {
+      soloditAvailable = true
+      logger.debug(`Solodit MCP healthy on port ${port}`)
+      break
     }
-    logger.debug(
-      `Solodit MCP not reachable after 3 retries on port ${port} — will retry on first use`,
-    )
-  })()
+  }
+  if (!soloditAvailable) {
+    logger.warn(`Solodit MCP not reachable after startup — monitoring will retry`)
+  }
 
   startMonitoring(port)
 }

package/src/tools/contract-analyzer-tool.ts

@@ -3,7 +3,7 @@ import { basename } from "node:path"
 import { type ToolContext, tool } from "@opencode-ai/plugin"
 import { findFoundryProjectDir } from "../shared/project-utils"
 import type { ContractProfile } from "../state/types"
-import { extractContractInfo } from "../utils/solidity-parser"
+import { extractContractInfo, parseExternalCalls } from "../utils/solidity-parser"
 
 type ContractAnalyzerArgs = {
   file_path: string
@@ -56,6 +56,24 @@ function collectRiskIndicators(source: string, existing: string[]): string[] {
   if (/\btx\.origin\b/.test(normalized)) {
     indicators.add("uses-tx-origin")
   }
+  if (/\.call\s*\{\s*value\s*:/.test(normalized)) {
+    indicators.add("uses-low-level-value-call")
+  }
+  if (normalized.includes(".call(")) {
+    indicators.add("uses-low-level-call")
+  }
+  if (normalized.includes("block.timestamp")) {
+    indicators.add("uses-block-timestamp")
+  }
+  if (normalized.includes("block.number")) {
+    indicators.add("uses-block-number")
+  }
+  if (normalized.includes("abi.encodepacked")) {
+    indicators.add("uses-abi-encode-packed")
+  }
+  if (/\becrecover\b/.test(normalized)) {
+    indicators.add("uses-ecrecover")
+  }
 
   const importLines = source
     .split("\n")
@@ -129,10 +147,74 @@ export async function executeContractAnalyzer(
       return createFailureProfile(contractName, filePath, "contract analysis aborted")
     }
 
+    const inheritanceRegex = /contract\s+(\w+)\s+is\s+([^{]+)/g
+    let sourceInheritance: string[] = []
+    let firstMatchParents: string[] | undefined
+    let regexMatch: RegExpExecArray | null = null
+
+    regexMatch = inheritanceRegex.exec(sourceText)
+    while (regexMatch !== null) {
+      const matchedName = regexMatch.at(1) ?? ""
+      const parents = (regexMatch.at(2) ?? "")
+        .split(",")
+        .map((p) => p.trim())
+        .filter(Boolean)
+
+      if (!firstMatchParents) {
+        firstMatchParents = parents
+      }
+
+      if (matchedName === contractName) {
+        sourceInheritance = parents
+        break
+      }
+
+      regexMatch = inheritanceRegex.exec(sourceText)
+    }
+
+    if (sourceInheritance.length === 0 && firstMatchParents) {
+      sourceInheritance = firstMatchParents
+    }
+
+    const mergedInheritance = [...new Set([...contractProfile.inheritance, ...sourceInheritance])]
+    const mergedExternalCalls = [
+      ...new Set([...contractProfile.externalCalls, ...parseExternalCalls(sourceText)]),
+    ]
+
+    // Extract modifiers from source text for each function
+    const visibilityKeywords = new Set([
+      "external",
+      "public",
+      "internal",
+      "private",
+      "view",
+      "pure",
+      "payable",
+      "virtual",
+      "override",
+      "returns",
+    ])
+    for (const fn of contractProfile.functions) {
+      if (!fn.name) continue
+      const escapedName = fn.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+      const fnPattern = new RegExp(`function\\s+${escapedName}\\s*\\([^)]*\\)\\s*([^{;]*)`)
+      const fnMatch = fnPattern.exec(sourceText)
+      if (!fnMatch?.[1]) continue
+
+      const afterParams = fnMatch[1]
+        .replace(/returns\s*\([^)]*\)/g, "")
+        .replace(/\([^)]*\)/g, "")
+        .trim()
+      const tokens = afterParams.match(/\b\w+\b/g) ?? []
+      fn.modifiers = tokens.filter((t) => !visibilityKeywords.has(t))
+    }
+
     return {
       ...contractProfile,
       name: contractProfile.name || contractName,
       filePath,
+      inheritance: mergedInheritance,
+      externalCalls: mergedExternalCalls,
       riskIndicators: collectRiskIndicators(sourceText, contractProfile.riskIndicators),
     }
   } catch (error) {

package/src/tools/forge-test-tool.ts

@@ -1,5 +1,6 @@
 import { type ToolContext, tool } from "@opencode-ai/plugin"
 import { resolveProjectDir } from "../shared/project-utils"
+import { extractJson } from "../utils/solidity-parser"
 
 type ForgeTestArgs = {
   target?: string
@@ -106,7 +107,53 @@ function parseTests(payload: ForgeTestPayload): {
 } {
   const collected: Array<ForgeTestItem | { skipped: true }> = []
 
-  if (Array.isArray(payload.tests)) {
+  const topLevelEntries = Object.entries(payload as unknown as Record<string, unknown>)
+  if (topLevelEntries.some(([key]) => key.includes(":"))) {
+    for (const [topLevelKey, suite] of topLevelEntries) {
+      if (!suite || typeof suite !== "object") {
+        continue
+      }
+
+      const suiteRecord = suite as Record<string, unknown>
+      const testResults = suiteRecord.test_results
+      if (!testResults || typeof testResults !== "object") {
+        continue
+      }
+
+      const contract = topLevelKey.split(":").at(1) ?? topLevelKey
+      for (const [name, details] of Object.entries(testResults)) {
+        if (!details || typeof details !== "object") {
+          continue
+        }
+
+        const detailsRecord = details as Record<string, unknown>
+        const statusValue =
+          typeof detailsRecord.status === "string" ? detailsRecord.status : undefined
+        const status = mapStatus(statusValue)
+        if (status === "skip") {
+          collected.push({ skipped: true })
+          continue
+        }
+
+        const kind = detailsRecord.kind
+        const kindRecord =
+          kind && typeof kind === "object" ? (kind as Record<string, unknown>) : undefined
+        const unit = kindRecord?.Unit
+        const unitRecord =
+          unit && typeof unit === "object" ? (unit as Record<string, unknown>) : undefined
+        const fuzz = kindRecord?.Fuzz
+        const fuzzRecord =
+          fuzz && typeof fuzz === "object" ? (fuzz as Record<string, unknown>) : undefined
+
+        collected.push({
+          name,
+          contract,
+          status,
+          gas: toNumber(unitRecord?.gas ?? fuzzRecord?.mean_gas),
+        })
+      }
+    }
+  } else if (Array.isArray(payload.tests)) {
     for (const item of payload.tests) {
       const status = mapStatus(item.status)
       if (status === "skip") {
@@ -311,7 +358,7 @@ export async function executeForgeTest(
 
     let payload: ForgeTestPayload
     try {
-      payload = JSON.parse(testResult.stdout) as ForgeTestPayload
+      payload = JSON.parse(extractJson(testResult.stdout, "{")) as ForgeTestPayload
     } catch {
       return fail("Invalid JSON output from forge test")
     }

package/src/tools/pattern-checker-tool.ts

@@ -62,7 +62,7 @@ type PatternCheckDependencies = {
   ) => ScvdIndexEntry[]
 }
 
-type LoadedPattern = {
+export type LoadedPattern = {
   name: string
   category: string
   severity: Match["severity"]
@@ -70,6 +70,9 @@ type LoadedPattern = {
   description: string
   exploitReference?: string
   source?: PatternSource
+  confidence?: "High" | "Medium" | "Low"
+  applies_to?: string[]
+  exclude_if?: string[]
 }
 
 export const PATTERN_PACK_VERSION = "1.0.0"
@@ -107,6 +110,9 @@ function normalizePatternDefinitions(
     regex: new RegExp(patternDef.regex),
     description: patternDef.description,
     ...(patternDef.exploit_ref ? { exploitReference: patternDef.exploit_ref } : {}),
+    ...(patternDef.confidence ? { confidence: patternDef.confidence } : {}),
+    ...(patternDef.applies_to ? { applies_to: patternDef.applies_to } : {}),
+    ...(patternDef.exclude_if ? { exclude_if: patternDef.exclude_if } : {}),
     source,
   }))
 }
@@ -235,16 +241,27 @@ function lineWindow(content: string, index: number): [number, number] {
   return [start, end]
 }
 
-function findMatches(file: string, patterns: LoadedPattern[]): Match[] {
+export function findMatches(file: string, patterns: LoadedPattern[]): Match[] {
   const content = readFileSync(file, "utf8")
   const matches: Match[] = []
 
+  // Strip comments and string literals to reduce false positives.
+  // Use a space-preserving approach so line numbers remain valid.
+  // Order: multi-line comments first (can contain //), then single-line, then strings.
+  const stripped = content
+    .replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, " "))
+    .replace(/\/\/[^\n]*/g, (m) => " ".repeat(m.length))
+    .replace(/"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'/g, (m) => {
+      const quote = m[0]
+      return `${quote}${" ".repeat(Math.max(0, m.length - 2))}${quote}`
+    })
+
   for (const pattern of patterns) {
     const regex = new RegExp(
       pattern.regex.source,
       pattern.regex.flags.includes("g") ? pattern.regex.flags : `${pattern.regex.flags}g`,
     )
-    for (const found of content.matchAll(regex)) {
+    for (const found of stripped.matchAll(regex)) {
       const index = found.index ?? 0
       matches.push({
         pattern: pattern.name,

package/src/tools/pattern-schema.ts

@@ -37,6 +37,9 @@ export const PatternDefinitionSchema = z.object({
   description: z.string().min(1),
   exploit_ref: z.string().url().optional(),
   remediation: z.string().optional(),
+  context: z.enum(["function-body", "contract-body", "file-level"]).optional(),
+  applies_to: z.array(z.string()).optional(),
+  exclude_if: z.array(z.string()).optional(),
 })
 
 export type PatternDefinition = z.infer<typeof PatternDefinitionSchema>

package/src/tools/report-generator-tool.ts

@@ -1,4 +1,9 @@
+import path from "node:path"
 import { type ToolContext, tool } from "@opencode-ai/plugin"
+import { loadArgusConfig } from "../config/loader"
+import type { ArgusConfig } from "../config/types"
+import { createLogger } from "../shared/logger"
+import { resolveProjectDir } from "../shared/project-utils"
 import type { AuditState, Finding, FindingSeverity } from "../state/types"
 
 type SeverityThreshold = "critical" | "high" | "medium" | "low" | "informational"
@@ -23,6 +28,11 @@ export type ReportGenerationResult = {
   report: string
   findingsCount: FindingsCount
   filename: string
+  filePath?: string
+}
+
+export type ReportGenerationDependencies = {
+  loadConfig?: (projectDir: string) => ArgusConfig
 }
 
 const SEVERITY_ORDER: FindingSeverity[] = ["Critical", "High", "Medium", "Low", "Informational"]
@@ -74,6 +84,118 @@ function emptyAuditState(findings: Finding[] = []): AuditState {
   }
 }
 
+/**
+ * Parse a location string like "File.sol:18-22" or "File.sol:18" into { file, lines }.
+ * Returns undefined if the string doesn't match a recognized format.
+ */
+export function parseLocationString(
+  location: string,
+): { file: string; lines: [number, number] } | undefined {
+  // "File.sol:18-22" or "File.sol:L18-L22"
+  const rangeMatch = location.match(/^(.+?):L?(\d+)\s*-\s*L?(\d+)$/)
+  if (rangeMatch) {
+    const file = rangeMatch.at(1)
+    const start = rangeMatch.at(2)
+    const end = rangeMatch.at(3)
+    if (file && start && end) {
+      return { file, lines: [Number(start), Number(end)] }
+    }
+  }
+  // "File.sol:18"
+  const singleMatch = location.match(/^(.+?):L?(\d+)$/)
+  if (singleMatch) {
+    const file = singleMatch.at(1)
+    const lineNum = singleMatch.at(2)
+    if (file && lineNum) {
+      const n = Number(lineNum)
+      return { file, lines: [n, n] }
+    }
+  }
+  return undefined
+}
+
+/**
+ * Normalize a raw finding object from agent output into the canonical field format.
+ * Handles common aliases:
+ *   - title/name → check
+ *   - location (string) → file + lines
+ *   - case-insensitive severity → capitalized
+ */
+export function normalizeRawFinding(raw: Record<string, unknown>): Record<string, unknown> {
+  const result = { ...raw }
+
+  // check: accept title, name as aliases
+  if (typeof result.check !== "string" || (result.check as string).length === 0) {
+    const alias = result.title ?? result.name
+    if (typeof alias === "string" && alias.length > 0) {
+      result.check = alias
+    }
+  }
+
+  // file + lines: accept location string as alias
+  if (typeof result.file !== "string" && typeof result.location === "string") {
+    const parsed = parseLocationString(result.location as string)
+    if (parsed) {
+      result.file = parsed.file
+      if (!Array.isArray(result.lines) || (result.lines as unknown[]).length !== 2) {
+        result.lines = parsed.lines
+      }
+    }
+  }
+
+  // lines: accept [start] as [start, start], accept line_start/line_end
+  if (!Array.isArray(result.lines) || (result.lines as unknown[]).length !== 2) {
+    if (Array.isArray(result.lines) && (result.lines as unknown[]).length === 1) {
+      const n = Number((result.lines as unknown[])[0])
+      if (!Number.isNaN(n)) {
+        result.lines = [n, n]
+      }
+    } else if (typeof result.line_start === "number" && typeof result.line_end === "number") {
+      result.lines = [result.line_start, result.line_end]
+    } else if (typeof result.line === "number") {
+      result.lines = [result.line, result.line]
+    }
+  }
+
+  // severity: case-insensitive normalization
+  if (typeof result.severity === "string") {
+    const lower = (result.severity as string).toLowerCase()
+    const SEVERITY_MAP: Record<string, string> = {
+      critical: "Critical",
+      high: "High",
+      medium: "Medium",
+      low: "Low",
+      informational: "Informational",
+      info: "Informational",
+    }
+    const mapped = SEVERITY_MAP[lower]
+    if (mapped) {
+      result.severity = mapped
+    }
+  }
+
+  // confidence: case-insensitive normalization
+  if (typeof result.confidence === "string") {
+    const lower = (result.confidence as string).toLowerCase()
+    const CONFIDENCE_MAP: Record<string, string> = {
+      high: "High",
+      medium: "Medium",
+      low: "Low",
+    }
+    const mapped = CONFIDENCE_MAP[lower]
+    if (mapped) {
+      result.confidence = mapped
+    }
+  }
+
+  // description: fall back to check if missing
+  if (typeof result.description !== "string" && typeof result.check === "string") {
+    result.description = result.check
+  }
+
+  return result
+}
+
 function hasMinimumFindingFields(
   f: unknown,
 ): f is { check: string; file: string; lines: [number, number] } {
@@ -143,10 +265,22 @@ export function parseAuditState(auditState: string): AuditState {
     )
   }
 
+  const logger = createLogger()
+
   if (Array.isArray(parsed)) {
-    const validFindings = (parsed as unknown[])
+    const rawItems = parsed as unknown[]
+    const normalized = rawItems
+      .filter((item): item is Record<string, unknown> => typeof item === "object" && item !== null)
+      .map((item) => normalizeRawFinding(item))
+    const validFindings = normalized
       .filter(hasMinimumFindingFields)
       .map((f) => normalizeFinding(f as Record<string, unknown>))
+    const dropped = rawItems.length - validFindings.length
+    if (dropped > 0) {
+      logger.warn(
+        `parseAuditState: ${dropped}/${rawItems.length} findings dropped (missing required fields after normalization)`,
+      )
+    }
     return emptyAuditState(validFindings)
   }
 
@@ -156,9 +290,19 @@ export function parseAuditState(auditState: string): AuditState {
     Array.isArray((parsed as AuditState).findings)
   ) {
     const state = parsed as AuditState
-    const validFindings = state.findings
+    const rawFindings = state.findings as unknown[]
+    const normalized = rawFindings
+      .filter((item): item is Record<string, unknown> => typeof item === "object" && item !== null)
+      .map((item) => normalizeRawFinding(item))
+    const validFindings = normalized
       .filter(hasMinimumFindingFields)
-      .map((f) => normalizeFinding(f as unknown as Record<string, unknown>))
+      .map((f) => normalizeFinding(f as Record<string, unknown>))
+    const dropped = rawFindings.length - validFindings.length
+    if (dropped > 0) {
+      logger.warn(
+        `parseAuditState: ${dropped}/${rawFindings.length} findings dropped (missing required fields after normalization)`,
+      )
+    }
     return {
       ...emptyAuditState(),
       ...state,
@@ -414,6 +558,7 @@ export function buildProvenanceAppendix(
 export async function executeReportGeneration(
   args: ReportGeneratorArgs,
   context: ToolContext,
+  deps: ReportGenerationDependencies = {},
 ): Promise<ReportGenerationResult> {
   const includeExecutiveSummary = args.include_executive_summary ?? true
   const threshold = args.severity_threshold ?? "low"
@@ -473,11 +618,31 @@ export async function executeReportGeneration(
 
   sections.push(buildProvenanceAppendix(state, threshold, findings.length))
 
-  return {
-    report: sections.join("\n\n"),
+  const reportMarkdown = sections.join("\n\n")
+  const safeName = args.project_name.replace(/[^a-zA-Z0-9-_]/g, "-")
+  const diskFilename = `${safeName}-${Date.now()}.md`
+
+  const result: ReportGenerationResult = {
+    report: reportMarkdown,
     findingsCount: counts,
     filename: `${args.project_name}-audit-report-${auditDate}.md`,
   }
+
+  try {
+    const loadConfig = deps.loadConfig ?? loadArgusConfig
+    const projectDir = resolveProjectDir(context)
+    const config = loadConfig(projectDir)
+    const outputDir = config.reporting?.output_dir ?? ".opencode/reports/"
+    const fullPath = path.join(projectDir, outputDir, diskFilename)
+    await Bun.write(fullPath, reportMarkdown)
+    result.filePath = fullPath
+  } catch (err: unknown) {
+    const logger = createLogger()
+    const message = err instanceof Error ? err.message : String(err)
+    logger.warn(`Failed to write report to disk: ${message}`)
+  }
+
+  return result
 }
 
 export const reportGeneratorTool = tool({

package/src/tools/solodit-search-tool.ts

@@ -1,6 +1,7 @@
 import type { ToolDefinition } from "@opencode-ai/plugin"
 import { type ToolContext, tool } from "@opencode-ai/plugin"
 import { createLogger } from "../shared/logger"
+import { soloditAvailable } from "../solodit-lifecycle"
 
 const logger = createLogger()
 
@@ -244,6 +245,24 @@ export async function executeSoloditSearch(
 
   context.metadata({ title: `Solodit search: ${query}` })
 
+  // Belt-and-suspenders: check if Solodit MCP is available, with 3s retry
+  // Skip check in test environment
+  if (!soloditAvailable && process.env.NODE_ENV !== "test") {
+    // Wait up to 3s for monitoring to flip the flag
+    for (let i = 0; i < 3 && !soloditAvailable; i++) {
+      await Bun.sleep(1000)
+    }
+    if (!soloditAvailable) {
+      return {
+        results: [],
+        totalFound: 0,
+        query,
+        error:
+          "Solodit MCP not available — server did not start. Results limited to local patterns.",
+      }
+    }
+  }
+
   const mcpCaller = callMcpTool ?? (hasMcpCapability(context) ? context.callMcpTool : undefined)
 
   if (!mcpCaller) {

package/src/utils/solidity-parser.ts

@@ -1,5 +1,8 @@
+import * as parser from "@solidity-parser/parser"
 import type { ContractProfile } from "../state/types"
 
+const EXTERNAL_CALL_METHODS = new Set(["call", "transfer", "send", "delegatecall", "staticcall"])
+
 interface ABIFunction {
   type: string
   name: string
@@ -24,8 +27,7 @@ interface StorageLayout {
  * prefix (e.g. forge table-format output, compilation progress).
  * Falls back to the original string if no JSON delimiter is found.
  */
-function extractJson(raw: string, opener: "[" | "{"): string {
-  const _closer = opener === "[" ? "]" : "}"
+export function extractJson(raw: string, opener: "[" | "{"): string {
   const start = raw.indexOf(opener)
   if (start === -1) return raw
 
@@ -69,6 +71,75 @@ function extractJson(raw: string, opener: "[" | "{"): string {
   return raw
 }
 
+function toRecord(value: unknown): Record<string, unknown> | undefined {
+  if (typeof value === "object" && value !== null) {
+    return value as Record<string, unknown>
+  }
+
+  return undefined
+}
+
+function extractNodeExpressionName(node: unknown): string | undefined {
+  const record = toRecord(node)
+  if (!record) return undefined
+
+  const type = typeof record.type === "string" ? record.type : undefined
+  if (!type) return undefined
+
+  if (type === "Identifier") {
+    return typeof record.name === "string" ? record.name : undefined
+  }
+
+  if (type === "ThisExpression") {
+    return "this"
+  }
+
+  if (type === "MemberAccess") {
+    const expressionName = extractNodeExpressionName(record.expression)
+    const memberName = typeof record.memberName === "string" ? record.memberName : undefined
+
+    if (expressionName && memberName) {
+      return `${expressionName}.${memberName}`
+    }
+
+    return expressionName ?? memberName
+  }
+
+  if (type === "IndexAccess") {
+    return extractNodeExpressionName(record.base)
+  }
+
+  if (type === "FunctionCall") {
+    return extractNodeExpressionName(record.expression)
+  }
+
+  return undefined
+}
+
+export function parseExternalCalls(sourceText: string): string[] {
+  try {
+    const ast = parser.parse(sourceText, { tolerant: true, loc: false, range: false })
+    const externalCalls = new Set<string>()
+
+    parser.visit(ast, {
+      MemberAccess(node: unknown) {
+        const record = toRecord(node)
+        if (!record) return
+
+        const memberName = typeof record.memberName === "string" ? record.memberName : undefined
+        if (!memberName || !EXTERNAL_CALL_METHODS.has(memberName)) return
+
+        const expressionName = extractNodeExpressionName(record.expression)
+        externalCalls.add(expressionName ? `${expressionName}.${memberName}` : memberName)
+      },
+    })
+
+    return [...externalCalls]
+  } catch {
+    return []
+  }
+}
+
 /**
  * Extract contract information using forge inspect
  * Runs forge inspect <contractName> abi and storage-layout