solidity-argus 0.2.0 → 0.3.2

package/src/hooks/event-hook.ts

@@ -1,33 +1,45 @@
-import type { AuditState } from "../state/types"
-import { createAuditState } from "../state/audit-state"
 import { createLogger } from "../shared/logger"
+import { createAuditState } from "../state/audit-state"
+import type { AuditState } from "../state/types"
+
+export type AuditEventType =
+  | "session.created"
+  | "session.idle"
+  | "session.error"
+  | "session.deleted"
+  | "audit.phase-changed"
+  | "audit.finding-added"
+  | "audit.complete"
 
 export type EventHookFn = (input: {
-  event: { type: string; sessionId?: string }
+  event: { type: string; sessionId?: string; properties?: Record<string, unknown> }
 }) => Promise<void>
 
-/**
- * Creates a session lifecycle event hook that manages audit state.
- *
- * Returns the hook function plus accessors for reading/writing the
- * closure-held audit state. Other hooks (compaction, tool tracking,
- * system prompt) share the same state instance via these accessors.
- */
-export function createEventHook(projectDir?: string): {
+export type EventSubHandler = (event: {
+  type: string
+  sessionId?: string
+  auditState: AuditState | null
+  setAuditState: (state: AuditState | null) => void
+}) => Promise<void>
+
+export function createEventHook(
+  projectDir?: string,
+  subHandlers: EventSubHandler[] = [],
+): {
   hook: EventHookFn
   getAuditState: () => AuditState | null
   setAuditState: (state: AuditState | null) => void
 } {
+  const logger = createLogger()
   let currentAuditState: AuditState | null = null
 
   const getAuditState = (): AuditState | null => currentAuditState
-
   const setAuditState = (state: AuditState | null): void => {
     currentAuditState = state
   }
 
   const hook: EventHookFn = async (input): Promise<void> => {
-    const { type } = input.event
+    const { type, sessionId } = input.event
 
     switch (type) {
       case "session.created": {
@@ -38,23 +50,23 @@ export function createEventHook(projectDir?: string): {
       }
 
       case "session.idle": {
-         if (currentAuditState) {
-           createLogger().debug(
-             `[state] Session idle — phase: ${currentAuditState.currentPhase}, findings: ${currentAuditState.findings.length}, contracts: ${currentAuditState.contractsReviewed.length}`
-           )
-         }
-         break
-       }
+        if (currentAuditState) {
+          logger.debug(
+            `Session idle — phase: ${currentAuditState.currentPhase}, findings: ${currentAuditState.findings.length}`,
+          )
+        }
+        break
+      }
 
       case "session.error": {
         if (currentAuditState) {
-          createLogger().error(
+          logger.error(
             `Session error — state snapshot: ${JSON.stringify({
               sessionId: currentAuditState.sessionId,
               phase: currentAuditState.currentPhase,
               findingsCount: currentAuditState.findings.length,
               contractsReviewed: currentAuditState.contractsReviewed,
-            })}`
+            })}`,
           )
         }
         break
@@ -65,10 +77,22 @@ export function createEventHook(projectDir?: string): {
         break
       }
 
-      // Unknown events: no-op — never throw
       default:
         break
     }
+
+    for (const handler of subHandlers) {
+      try {
+        await handler({
+          type,
+          sessionId,
+          auditState: currentAuditState,
+          setAuditState,
+        })
+      } catch (error) {
+        logger.error(`Sub-handler failed for event ${type}:`, error)
+      }
+    }
   }
 
   return { hook, getAuditState, setAuditState }

package/src/hooks/hook-system.ts

@@ -1,9 +1,9 @@
-import type { HookName } from "./types";
+import type { HookName } from "./types"
 
 export function createHookGuard(disabledHooks: string[]) {
-  const disabledSet = new Set(disabledHooks);
+  const disabledSet = new Set(disabledHooks)
 
   return function isHookEnabled(name: HookName): boolean {
-    return !disabledSet.has(name);
-  };
+    return !disabledSet.has(name)
+  }
 }

package/src/hooks/index.ts

@@ -1,5 +1,5 @@
-export { createHookGuard } from "./hook-system";
-export { safeCreateHook } from "./safe-create-hook";
-export { createEventHookV2 } from "./event-hook-v2";
-export type { HookName } from "./types";
-export type { EventHookV2Fn, AuditEventType, EventSubHandler } from "./event-hook-v2";
+export type { AuditEventType, EventHookFn, EventSubHandler } from "./event-hook"
+export { createEventHook } from "./event-hook"
+export { createHookGuard } from "./hook-system"
+export { safeCreateHook } from "./safe-create-hook"
+export type { HookName } from "./types"

package/src/hooks/knowledge-sync-hook.ts

@@ -1,8 +1,8 @@
 import os from "node:os"
 import path from "node:path"
-import { ScvdClient } from "../knowledge/scvd-client"
-import { syncIncremental, type SyncResult } from "../knowledge/scvd-sync"
 import type { ArgusConfig } from "../config/types"
+import { ScvdClient } from "../knowledge/scvd-client"
+import { type SyncResult, syncIncremental } from "../knowledge/scvd-sync"
 import { createLogger } from "../shared/logger"
 
 export type KnowledgeSyncDependencies = {
@@ -19,14 +19,14 @@ function defaultDependencies(): Required<KnowledgeSyncDependencies> {
     syncIncrementalFn: async (client: unknown, indexPath: string) =>
       syncIncremental(client as ScvdClient, indexPath),
     log: (message: string) => {
-       createLogger().info(message)
-     },
+      createLogger().info(message)
+    },
   }
 }
 
 export function createKnowledgeSyncHook(
   argusConfig: ArgusConfig,
-  deps: KnowledgeSyncDependencies = {}
+  deps: KnowledgeSyncDependencies = {},
 ): () => void {
   const dependencies = { ...defaultDependencies(), ...deps }
 
@@ -36,23 +36,20 @@ export function createKnowledgeSyncHook(
     }
 
     const apiUrl = argusConfig.knowledge?.scvd?.apiUrl ?? DEFAULT_SCVD_API_URL
-    const indexPath = path.join(
-      os.homedir(),
-      ".cache",
-      "solidity-argus",
-      "scvd-index.json"
-    )
+    const indexPath = path.join(os.homedir(), ".cache", "solidity-argus", "scvd-index.json")
 
     Promise.resolve().then(async () => {
-       try {
-         const client = dependencies.createClient(apiUrl)
-         const result = await dependencies.syncIncrementalFn(client, indexPath)
-         if (result.newFindings > 0) {
-           dependencies.log(
-             `[argus] SCVD index updated: ${result.newFindings} new findings (total: ${result.totalIndexed})`
-           )
-         }
-       } catch (_e) { /* non-critical: sync errors are logged above */ }
-     })
+      try {
+        const client = dependencies.createClient(apiUrl)
+        const result = await dependencies.syncIncrementalFn(client, indexPath)
+        if (result.newFindings > 0) {
+          dependencies.log(
+            `[argus] SCVD index updated: ${result.newFindings} new findings (total: ${result.totalIndexed})`,
+          )
+        }
+      } catch (_e) {
+        createLogger().debug("Knowledge sync failed during auto-sync")
+      }
+    })
   }
 }

package/src/hooks/recon-context-builder.ts

@@ -1,6 +1,6 @@
-import type { ProjectConfig } from "../utils/project-detector"
-import type { DependencyRisk } from "../utils/dependency-scanner"
 import type { AuditArtifact } from "../utils/audit-artifact-detector"
+import type { DependencyRisk } from "../utils/dependency-scanner"
+import type { ProjectConfig } from "../utils/project-detector"
 
 export interface ReconContext {
   projectConfig: ProjectConfig | null

package/src/hooks/safe-create-hook.ts

@@ -1,14 +1,13 @@
 import { createLogger } from "../shared/logger"
 
-export function safeCreateHook<T>(
-  factory: () => T,
-  hookName: string
-): T | undefined {
+export function safeCreateHook<T>(factory: () => T, hookName: string): T | undefined {
   try {
-    return factory();
+    return factory()
   } catch (error) {
     const logger = createLogger()
-    logger.error(`Failed to create hook "${hookName}": ${error instanceof Error ? error.message : String(error)}`)
-    return undefined;
+    logger.error(
+      `Failed to create hook "${hookName}": ${error instanceof Error ? error.message : String(error)}`,
+    )
+    return undefined
   }
 }

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

@@ -1,6 +1,6 @@
-import type { AuditState, FindingSeverity, FuzzCounterexample, SoloditResult } from "../state/types"
 import type { FindingStore } from "../state/finding-store"
 import { createFindingStore } from "../state/finding-store"
+import type { AuditState, FindingSeverity, FuzzCounterexample, SoloditResult } from "../state/types"
 
 type ToolHookInput = {
   tool: string
@@ -8,6 +8,11 @@ type ToolHookInput = {
   result: string
 }
 
+type ToolExecutionMetadata = {
+  tool: string
+  findingsCount: number
+}
+
 const VALID_SEVERITIES: ReadonlySet<string> = new Set([
   "Critical",
   "High",
@@ -16,11 +21,7 @@ const VALID_SEVERITIES: ReadonlySet<string> = new Set([
   "Informational",
 ])
 
-const VALID_CONFIDENCES: ReadonlySet<string> = new Set([
-  "High",
-  "Medium",
-  "Low",
-])
+const VALID_CONFIDENCES: ReadonlySet<string> = new Set(["High", "Medium", "Low"])
 
 function toSeverity(value: unknown): FindingSeverity {
   if (typeof value === "string" && VALID_SEVERITIES.has(value)) {
@@ -55,10 +56,7 @@ function toRecord(value: unknown): Record<string, unknown> | undefined {
   return undefined
 }
 
-function processSlitherResult(
-  parsed: Record<string, unknown>,
-  store: FindingStore
-): number {
+function processSlitherResult(parsed: Record<string, unknown>, store: FindingStore): number {
   const findings = parsed.findings
   if (!Array.isArray(findings)) return 0
 
@@ -96,10 +94,7 @@ function processSlitherResult(
   return count
 }
 
-function processPatternResult(
-  parsed: Record<string, unknown>,
-  store: FindingStore
-): number {
+function processPatternResult(parsed: Record<string, unknown>, store: FindingStore): number {
   const sources = parsed.sources
   if (!Array.isArray(sources)) return 0
 
@@ -145,10 +140,7 @@ function processPatternResult(
   return count
 }
 
-function processContractAnalyzerResult(
-  parsed: Record<string, unknown>,
-  state: AuditState
-): void {
+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)) {
@@ -166,15 +158,11 @@ function processContractAnalyzerResult(
   }
 }
 
-function processFuzzResult(
-  parsed: Record<string, unknown>,
-  state: AuditState
-): void {
+function processFuzzResult(parsed: Record<string, unknown>, state: AuditState): void {
   const counterexamples = parsed.counterexamples
   if (!Array.isArray(counterexamples) || counterexamples.length === 0) return
 
-  const totalRuns =
-    typeof parsed.totalRuns === "number" ? parsed.totalRuns : 0
+  const totalRuns = typeof parsed.totalRuns === "number" ? parsed.totalRuns : 0
 
   state.fuzzCounterexamples ??= []
 
@@ -185,8 +173,13 @@ function processFuzzResult(
     const testName = ce.testName
     if (typeof testName !== "string") continue
 
-    const rawInputs = toRecord(ce.inputs)
-    const inputs = rawInputs ? Object.values(rawInputs).map(String) : []
+    const rawInputs = ce.inputs
+    const inputs = Array.isArray(rawInputs)
+      ? rawInputs.map(String)
+      : (() => {
+          const rec = toRecord(rawInputs)
+          return rec ? Object.values(rec).map(String) : []
+        })()
 
     const entry: FuzzCounterexample = {
       testName,
@@ -203,26 +196,20 @@ function processFuzzResult(
   }
 }
 
-function processSoloditResult(
-  parsed: Record<string, unknown>,
-  state: AuditState
-): void {
+function processSoloditResult(parsed: Record<string, unknown>, state: AuditState): void {
   const query = typeof parsed.query === "string" ? parsed.query : ""
   const results = Array.isArray(parsed.results) ? parsed.results : []
-  const totalFound =
-    typeof parsed.totalFound === "number" ? parsed.totalFound : results.length
-
-  const topResults: SoloditResult["topResults"] = results
-    .slice(0, 5)
-    .map((raw) => {
-      const r = toRecord(raw)
-      return {
-        title: typeof r?.title === "string" ? r.title : "",
-        severity: typeof r?.severity === "string" ? r.severity : "",
-        url: typeof r?.url === "string" ? r.url : "",
-        protocol: typeof r?.protocol === "string" ? r.protocol : "",
-      }
-    })
+  const totalFound = typeof parsed.totalFound === "number" ? parsed.totalFound : results.length
+
+  const topResults: SoloditResult["topResults"] = results.slice(0, 5).map((raw) => {
+    const r = toRecord(raw)
+    return {
+      title: typeof r?.title === "string" ? r.title : "",
+      severity: typeof r?.severity === "string" ? r.severity : "",
+      url: typeof r?.url === "string" ? r.url : "",
+      protocol: typeof r?.protocol === "string" ? r.protocol : "",
+    }
+  })
 
   state.soloditResults ??= []
   state.soloditResults.push({
@@ -246,11 +233,7 @@ function processSoloditResult(
  * 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 {
+function recordToolExecution(state: AuditState, toolName: string, findingsCount: number): void {
   const now = Date.now()
   state.toolsExecuted.push({
     tool: toolName,
@@ -269,7 +252,8 @@ function recordToolExecution(
  * Findings are deduplicated via the FindingStore (by check+file+lines).
  */
 export function createToolTrackingHook(
-  getAuditState: () => AuditState | null
+  getAuditState: () => AuditState | null,
+  onStateChanged?: (metadata: ToolExecutionMetadata) => void,
 ): (input: ToolHookInput) => Promise<void> {
   const storesByState = new WeakMap<AuditState, FindingStore>()
 
@@ -296,6 +280,22 @@ export function createToolTrackingHook(
 
     const { state: auditState, store } = resolved
 
+    // 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) {
+        auditState.skillsLoaded ??= []
+        if (!auditState.skillsLoaded.includes(skillName)) {
+          auditState.skillsLoaded.push(skillName)
+        }
+      }
+      recordToolExecution(auditState, input.tool, 0)
+      onStateChanged?.({ tool: input.tool, findingsCount: 0 })
+      return
+    }
+
     let parsed: unknown
     try {
       parsed = JSON.parse(input.result)
@@ -321,13 +321,72 @@ 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
+      case "argus_generate_report": {
+        auditState.reportGenerated = true
+        break
+      }
+      case "argus_sync_knowledge": {
+        const success = record.success === true
+        auditState.knowledgeSynced = { success, timestamp: Date.now() }
+        break
+      }
+      case "argus_forge_coverage": {
+        const reportObj = toRecord(record.report)
+        const files = reportObj?.files
+        if (Array.isArray(files)) {
+          auditState.coverageReport = {
+            files: files
+              .filter((f): f is Record<string, unknown> => !!f && typeof f === "object")
+              .map((f) => ({
+                path: typeof f.path === "string" ? f.path : "unknown",
+                linesPct: typeof f.linesPct === "number" ? f.linesPct : 0,
+                statementsPct: typeof f.statementsPct === "number" ? f.statementsPct : 0,
+                branchesPct: typeof f.branchesPct === "number" ? f.branchesPct : 0,
+                functionsPct: typeof f.functionsPct === "number" ? f.functionsPct : 0,
+              })),
+          }
+        }
+        break
+      }
+      case "argus_proxy_detection": {
+        if (record.isProxy === true) {
+          auditState.proxyContracts ??= []
+          auditState.proxyContracts.push({
+            file: typeof record.file === "string" ? record.file : "unknown",
+            proxyType: typeof record.proxyType === "string" ? record.proxyType : "unknown",
+            indicators: Array.isArray(record.indicators)
+              ? record.indicators.filter((i): i is string => typeof i === "string")
+              : [],
+          })
+        }
+        break
+      }
+      case "argus_gas_analysis": {
+        const hotspots = record.hotspots
+        if (Array.isArray(hotspots)) {
+          auditState.gasHotspots = hotspots
+            .filter((h): h is Record<string, unknown> => !!h && typeof h === "object")
+            .map((h) => ({
+              contract: typeof h.contract === "string" ? h.contract : "unknown",
+              function: typeof h.function === "string" ? h.function : "unknown",
+              avgGas: typeof h.avgGas === "number" ? h.avgGas : 0,
+            }))
+        }
+        break
+      }
     }
 
     recordToolExecution(auditState, input.tool, findingsCount)
+    onStateChanged?.({ tool: input.tool, findingsCount })
   }
 }

package/src/hooks/types.ts

@@ -12,4 +12,5 @@ export type HookName =
   | "tool-error-recovery"
   | "context-window-monitor"
   | "tool-output-truncator"
-  | "audit-continuation";
+  | "audit-continuation"
+  | "system-prompt"

package/src/index.ts

@@ -1,54 +1,41 @@
 import type { Plugin } from "@opencode-ai/plugin"
 import { loadArgusConfig } from "./config/loader"
-import { createHookGuard } from "./hooks/hook-system"
-import { createTools } from "./create-tools"
 import { createHooks } from "./create-hooks"
 import { createManagers } from "./create-managers"
+import { createTools } from "./create-tools"
+import type { Dispatcher } from "./features/background-agent/background-manager"
+import { createHookGuard } from "./hooks/hook-system"
 import { createPluginInterface } from "./plugin-interface"
-import { checkSoloditHealth } from "./utils/solodit-health"
-import { createLogger } from "./shared/logger"
-
-async function startSoloditMcp(port: number): Promise<void> {
-  const logger = createLogger()
-
-  // Health check before spawn: if already reachable, skip spawn
-  const health = await checkSoloditHealth(port, true)
-  if (health.reachable) {
-    logger.debug(`Solodit MCP already running on port ${port} — skipping spawn`)
-    return
-  }
-
-  const child = Bun.spawn(["npx", "-y", "@lyuboslavlyubenov/solodit-mcp"], {
-    stdin: "ignore",
-    stdout: "ignore",
-    stderr: "ignore",
-    env: { ...process.env, PORT: String(port) },
-  })
-  child.unref()
-
-  // Health check after spawn: wait 2s, then ping
-  setTimeout(async () => {
-    const health = await checkSoloditHealth(port, true)
-    if (!health.reachable) {
-      logger.debug(`Solodit MCP not yet reachable on port ${port} — will retry on first use`)
-    } else {
-      logger.debug(`Solodit MCP healthy on port ${port}`)
-    }
-  }, 2000)
-}
+import { startSoloditMcp } from "./solodit-lifecycle"
 
 const ArgusPlugin: Plugin = async (ctx) => {
   const projectDir = ctx.directory ?? process.cwd()
   const config = loadArgusConfig(projectDir)
 
   if (config.solodit?.enabled !== false) {
-    // Fire-and-forget: startSoloditMcp is now async but we don't await
-    // to avoid blocking plugin initialization
-    startSoloditMcp(config.solodit?.port ?? 3000)
+    await startSoloditMcp(config.solodit?.port ?? 3000)
   }
 
   const isHookEnabled = createHookGuard(config.disabled_hooks)
-  const managers = createManagers({ projectDir, config })
+  const taskCandidate = (ctx as Record<string, unknown>).task
+  const backgroundDispatcher: Dispatcher | undefined =
+    typeof taskCandidate === "function"
+      ? async (agentName: string, prompt: string) => {
+          const result = await taskCandidate(agentName, prompt)
+          if (typeof result === "string") {
+            return result
+          }
+          if (typeof result === "object" && result !== null) {
+            const taskId = (result as Record<string, unknown>).task_id
+            if (typeof taskId === "string") {
+              return taskId
+            }
+          }
+          return `task-${Date.now()}`
+        }
+      : undefined
+
+  const managers = createManagers({ projectDir, config, backgroundDispatcher })
   const tools = createTools(config)
   const hooks = createHooks({ config, managers, projectDir, isHookEnabled })