solidity-argus 0.5.6 → 0.5.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solidity-argus",
-  "version": "0.5.6",
+  "version": "0.5.7",
   "description": "Solidity smart contract security auditing plugin for OpenCode — 5 specialized agents, 15 tools (14 core + optional Solodit), and a curated vulnerability knowledge base",
   "keywords": [
     "solidity",

package/src/agents/pythia-prompt.ts

@@ -124,7 +124,12 @@ This ensures Pythia always delivers research value, even when Solodit has no dir
 
 ## 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.
+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. You load them with \`argus_skill_load\`.
+
+**CRITICAL — use the right tool**:
+- For ALL vulnerability, protocol, checklist, methodology, and case-study knowledge, use \`argus_skill_load\` with the exact skill name (e.g. \`argus_skill_load({ name: "reentrancy" })\`).
+- **NEVER** call the generic OpenCode \`skill\` tool. It does not know about Argus skills like \`reentrancy\`, \`access-control\`, \`oracle-manipulation\`, etc., and will return "Skill or command not found" errors.
+- If you are unsure whether a name is an Argus skill, default to \`argus_skill_load\` — it is the only correct loader for audit knowledge.
 
 **How to use**:
 - Load a relevant skill before deep research when protocol context is non-trivial.

package/src/agents/scribe-prompt.ts

@@ -65,10 +65,12 @@ Argus provides you with a \`run_id\`. Your job: read findings, deduplicate, enri
 
    This writes the source-of-truth JSON to disk at \`.argus/runs/{run_id}/deduped-findings.json\`.
 
-5. **Generate report**: Call \`argus_generate_report\` with:
+5. **Generate report**: Call \`argus_generate_report\` with EXACTLY these arguments (and nothing else):
    - \`project_name\`: the project name
    - \`scope\`: list of audited files
-   - \`run_id\`: the run ID (the tool reads your persisted deduped findings from disk)
+   - \`run_id\`: the run ID (the tool reads your persisted deduped findings from disk and resolves the canonical envelope automatically)
+
+   **DO NOT** pass \`report_input\`, \`findings\`, \`toolsExecuted\`, \`session_id\`, or any other field — the tool reads them from durable state on disk. Passing them risks contract-mismatch failures.
 
 6. **Limitations disclosure**: If any tool failed or was absent, add a \`## Limitations\` section.
 

package/src/cli/commands/install.ts

@@ -1,57 +1,98 @@
-import { existsSync, readFileSync, writeFileSync } from "node:fs"
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import { homedir } from "node:os"
-import { join } from "node:path"
+import { dirname, join } from "node:path"
 import { cliOutput } from "../cli-output"
+import { confirm } from "../tui-prompts"
 import type { CliCommand } from "../types"
 
 const GREEN = "\x1b[32m"
 const YELLOW = "\x1b[33m"
 const RESET = "\x1b[0m"
 
+function resolveHome(homeOverride?: string): string {
+  if (homeOverride && homeOverride.length > 0) return homeOverride
+  const envHome = process.env.HOME ?? process.env.USERPROFILE
+  if (envHome && envHome.length > 0) return envHome
+  return homedir()
+}
+
+function localConfigPath(): string {
+  return join(process.cwd(), "opencode.json")
+}
+
+function globalConfigPath(homeOverride?: string): string {
+  return join(resolveHome(homeOverride), ".config", "opencode", "opencode.json")
+}
+
 export function findOpencodeConfig(homeOverride?: string): string | null {
-  const cwd = process.cwd()
-  const localPath = join(cwd, "opencode.json")
-  if (existsSync(localPath)) return localPath
+  const local = localConfigPath()
+  if (existsSync(local)) return local
 
-  const home = homeOverride ?? homedir()
-  const globalPath = join(home, ".config", "opencode", "opencode.json")
-  if (existsSync(globalPath)) return globalPath
+  const global = globalConfigPath(homeOverride)
+  if (existsSync(global)) return global
 
   return null
 }
 
+function addPluginToConfig(configPath: string): { added: boolean; ok: boolean } {
+  try {
+    let config: Record<string, unknown>
+    if (existsSync(configPath)) {
+      const content = readFileSync(configPath, "utf-8")
+      config = JSON.parse(content)
+    } else {
+      mkdirSync(dirname(configPath), { recursive: true })
+      config = {}
+    }
+
+    const plugins = Array.isArray(config.plugin) ? (config.plugin as string[]) : []
+    if (plugins.includes("solidity-argus")) {
+      cliOutput.log(`${GREEN}✓${RESET} solidity-argus already registered in ${configPath}`)
+      return { added: false, ok: true }
+    }
+
+    plugins.push("solidity-argus")
+    config.plugin = plugins
+    writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`)
+    cliOutput.log(`${GREEN}✓${RESET} Added solidity-argus to ${configPath}`)
+    return { added: true, ok: true }
+  } catch (_error) {
+    cliOutput.error(`${YELLOW}⚠${RESET} Failed to update ${configPath}`)
+    return { added: false, ok: false }
+  }
+}
+
 export const installCommand: CliCommand = {
   name: "install",
-  description: "Register solidity-argus in your OpenCode config",
-  async execute(_args: string[]): Promise<number> {
-    const configPath = findOpencodeConfig()
-
-    if (!configPath) {
-      cliOutput.error(
-        `${YELLOW}⚠${RESET} opencode.json not found — create one first, or run: opencode init`,
-      )
-      return 1
-    }
+  description: "Register solidity-argus in your OpenCode config (use --global for ~/.config/opencode)",
+  async execute(args: string[]): Promise<number> {
+    const isGlobal = args.includes("--global") || args.includes("-g")
+    const local = localConfigPath()
 
-    try {
-      const content = readFileSync(configPath, "utf-8")
-      const config = JSON.parse(content)
-      const plugins: string[] = config.plugin ?? []
+    if (existsSync(local) && !isGlobal) {
+      return addPluginToConfig(local).ok ? 0 : 1
+    }
 
-      if (plugins.includes("solidity-argus")) {
-        cliOutput.log(`${GREEN}✓${RESET} solidity-argus already registered in ${configPath}`)
-        return 0
-      }
+    if (isGlobal) {
+      return addPluginToConfig(globalConfigPath()).ok ? 0 : 1
+    }
 
-      plugins.push("solidity-argus")
-      config.plugin = plugins
-      writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`)
+    const global = globalConfigPath()
+    cliOutput.warn(
+      `${YELLOW}⚠${RESET} No opencode.json found in current directory (${process.cwd()}).`,
+    )
+    cliOutput.warn(
+      `  Installing globally would write to ${global} and load solidity-argus in EVERY OpenCode session.`,
+    )
+    cliOutput.warn(`  To install globally on purpose, re-run with: argus install --global`)
+    cliOutput.warn(`  To install for this project, first create an opencode.json in this directory.`)
 
-      cliOutput.log(`${GREEN}✓${RESET} Added solidity-argus to ${configPath}`)
+    const proceed = await confirm("Install globally anyway?", false)
+    if (!proceed) {
+      cliOutput.log("Aborted. No changes made.")
       return 0
-    } catch (_error) {
-      cliOutput.error(`${YELLOW}⚠${RESET} Failed to update ${configPath}`)
-      return 1
     }
+
+    return addPluginToConfig(global).ok ? 0 : 1
   },
 }

package/src/create-hooks.ts

@@ -15,6 +15,7 @@ import {
 } from "./features/persistent-state/event-sink"
 import {
   materializeFindings,
+  materializeFindingsForRun,
   materializeReportInput,
 } from "./features/persistent-state/findings-materializer"
 import { recordRun, updateRunStatus } from "./features/persistent-state/global-run-index"
@@ -874,34 +875,17 @@ export function createHooks(args: {
       )
     : undefined
 
-  const materializeFindingsForRun = async (
+  const runMaterializeFindings = (
     runId: string,
     projectDirForRun: string,
     sessionIdForRun: string | undefined,
     trigger: "session.idle" | "session.deleted" | "tool.execute.after",
     failFast = false,
-  ): Promise<void> => {
-    if (!runId || runId.length === 0) {
-      return
-    }
-
-    try {
-      await materializeFindings(runId, projectDirForRun, sessionIdForRun, {
-        validateSessionId: false,
-        requireEvents: true,
-      })
-    } catch (error) {
-      if (failFast) {
-        throw new Error(
-          `Failed to materialize findings artifact on ${trigger} for run ${runId}: ${error instanceof Error ? error.message : String(error)}`,
-        )
-      }
-
-      logger.warn(
-        `Failed to materialize findings artifact on ${trigger} for run ${runId}: ${error instanceof Error ? error.message : String(error)}`,
-      )
-    }
-  }
+  ): Promise<void> =>
+    materializeFindingsForRun(runId, projectDirForRun, sessionIdForRun, trigger, {
+      failFast,
+      warn: (msg) => logger.warn(msg),
+    })
 
   const safeEventHook = isHookEnabled("event")
     ? safeCreateHook(
@@ -920,7 +904,7 @@ export function createHooks(args: {
 
               if (hasNewFinalization && finalizationResult.runId.length > 0) {
                 try {
-                  await materializeFindingsForRun(
+                  await runMaterializeFindings(
                     finalizationResult.runId,
                     projectDir,
                     eventSessionId,
@@ -1093,12 +1077,12 @@ export function createHooks(args: {
               )
             }
 
-            await materializeFindingsForRun(
+            await runMaterializeFindings(
               state.sessionId,
               state.projectDir,
               input.sessionID,
               "tool.execute.after",
-              true,
+              false,
             )
 
             try {

package/src/features/persistent-state/findings-materializer.ts

@@ -12,6 +12,16 @@ import type { CanonicalFinding, CanonicalToolExecution, ReportInput } from "../.
 import { SCHEMA_VERSION } from "../../state/schemas"
 import { readEvents } from "./event-sink"
 
+export type MaterializeFindingsTrigger =
+  | "session.idle"
+  | "session.deleted"
+  | "tool.execute.after"
+
+export interface MaterializeFindingsForRunOptions {
+  failFast?: boolean
+  warn?: (message: string) => void
+}
+
 export interface FindingsArtifact {
   run_id: string
   session_id: string
@@ -78,6 +88,30 @@ export async function materializeFindings(
   return artifact
 }
 
+export async function materializeFindingsForRun(
+  runId: string,
+  projectDir: string,
+  sessionId: string | undefined,
+  trigger: MaterializeFindingsTrigger,
+  options: MaterializeFindingsForRunOptions = {},
+): Promise<void> {
+  if (!runId || runId.length === 0) return
+
+  const { failFast = false, warn } = options
+  try {
+    await materializeFindings(runId, projectDir, sessionId, {
+      validateSessionId: false,
+      requireEvents: true,
+    })
+  } catch (error) {
+    const message = `Failed to materialize findings artifact on ${trigger} for run ${runId}: ${error instanceof Error ? error.message : String(error)}`
+    if (failFast) {
+      throw new Error(message)
+    }
+    warn?.(message)
+  }
+}
+
 export async function materializeReportInput(
   runId: string,
   projectDir: string,

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

@@ -348,6 +348,11 @@ function processToolResult(
     }
 
     if (config.extractOptionalFields) {
+      findingPayload.impact = typeof item.impact === "string" ? item.impact : undefined
+      findingPayload.recommendation =
+        typeof item.recommendation === "string" ? item.recommendation : undefined
+      findingPayload.proofOfConcept =
+        typeof item.proofOfConcept === "string" ? item.proofOfConcept : undefined
       findingPayload.remediation =
         typeof item.remediation === "string" ? item.remediation : undefined
       findingPayload.exploitReference =

package/src/tools/record-finding-tool.ts

@@ -16,10 +16,15 @@ type RecordFindingResponse = {
     id: string
     check: string
     severity: string
+    confidence: string
     file: string
     description: string
     lines: [number, number]
     source: string
+    reported_by_agent: string
+    impact?: string
+    recommendation?: string
+    proofOfConcept?: string
   }>
   schema_version: string
   note: string
@@ -178,10 +183,15 @@ export async function executeRecordFinding(
       id: f.id,
       check: f.check,
       severity: f.severity,
+      confidence: f.confidence,
       file: f.file,
       description: f.description,
       lines: f.lines,
       source: f.source,
+      reported_by_agent: f.reported_by_agent,
+      ...(f.impact !== undefined ? { impact: f.impact } : {}),
+      ...(f.recommendation !== undefined ? { recommendation: f.recommendation } : {}),
+      ...(f.proofOfConcept !== undefined ? { proofOfConcept: f.proofOfConcept } : {}),
     })),
     schema_version: SCHEMA_VERSION,
     note: "Findings recorded to event journal. The system assigns the canonical run_id automatically — use the run_id from <argus-context> for Scribe dispatch.",

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

@@ -14,13 +14,14 @@ import { resolveProjectDir } from "../shared/project-utils"
 import { resolveReportPath } from "../shared/report-path-resolver"
 import { isNonEmptyString } from "../shared/type-guards"
 import { SEVERITY_RANK } from "../shared/validation-constants"
+import { normalizeToCanonicalFinding } from "../state/adapters"
 import {
   compareIssueFingerprintSets,
   dedupeFindingsForFinalOutput,
 } from "../state/finding-aggregation"
 import { projectFindings, stableHash } from "../state/projectors"
 import { type ReportInput, SCHEMA_VERSION, validateReportInput } from "../state/schemas"
-import type { AuditState, Finding, FindingSeverity } from "../state/types"
+import type { ArgusAgentName, AuditState, Finding, FindingSeverity } from "../state/types"
 import { checkReportPreflight } from "./report-preflight"
 
 type SeverityThreshold = "critical" | "high" | "medium" | "low" | "informational"
@@ -304,6 +305,37 @@ type ParseReportInputResult = {
   diagnostics: DropDiagnostic[]
 }
 
+const VALID_AGENT_VALUES = new Set<ArgusAgentName>([
+  "argus",
+  "sentinel",
+  "pythia",
+  "scribe",
+  "unknown",
+])
+
+function normalizeDedupedFindings(
+  rawFindings: unknown[],
+  runId: string,
+  projectDir: string,
+  dedupedBy: string,
+): Record<string, unknown>[] {
+  const reportedByAgent: ArgusAgentName = VALID_AGENT_VALUES.has(dedupedBy as ArgusAgentName)
+    ? (dedupedBy as ArgusAgentName)
+    : "scribe"
+  return rawFindings.map((raw, index) => {
+    const input = raw && typeof raw === "object" ? (raw as Record<string, unknown>) : {}
+    const normalized = normalizeRawFinding(input)
+    const result = normalizeToCanonicalFinding(
+      normalized,
+      runId,
+      index + 1,
+      { reportedByAgent },
+      projectDir,
+    )
+    return result.data as unknown as Record<string, unknown>
+  })
+}
+
 function diagnosticsSummary(diagnostics: DropDiagnostic[]): string {
   return diagnostics.map((diag) => `${diag.reason.code}:${diag.reason.message}`).join("; ")
 }
@@ -576,6 +608,7 @@ function parseReportInputPayload(
       try {
         const dedupedArtifact = JSON.parse(readFileSync(dedupedFile, "utf-8")) as {
           findings?: unknown[]
+          deduped_by?: string
         }
         if (Array.isArray(dedupedArtifact.findings) && dedupedArtifact.findings.length > 0) {
           const reportInputFile = resolver.paths().reportInputFile
@@ -590,15 +623,64 @@ function parseReportInputPayload(
               /* use empty base */
             }
           }
-          const merged = {
+          const normalizedFindings = normalizeDedupedFindings(
+            dedupedArtifact.findings,
+            effectiveRunId,
+            projectDir,
+            typeof dedupedArtifact.deduped_by === "string"
+              ? dedupedArtifact.deduped_by
+              : "scribe",
+          )
+          const merged: Record<string, unknown> = {
             ...baseInput,
             run_id: effectiveRunId,
-            findings: dedupedArtifact.findings,
+            findings: normalizedFindings,
+          }
+          normalizeToolsExecutedDefaults(merged, effectiveRunId, diagnostics)
+          if (typeof merged.seq !== "number" || (merged.seq as number) < 0) {
+            merged.seq = 0
+          }
+          if (typeof merged.session_id !== "string" || (merged.session_id as string).length === 0) {
+            merged.session_id = "unknown"
+          }
+          if (
+            typeof merged.tool_call_id !== "string" ||
+            (merged.tool_call_id as string).length === 0
+          ) {
+            merged.tool_call_id = `deduped:${effectiveRunId}`
+          }
+          if (typeof merged.source !== "string" || (merged.source as string).length === 0) {
+            merged.source = "deduped-findings"
+          }
+          if (
+            typeof merged.schema_version !== "string" ||
+            merged.schema_version !== SCHEMA_VERSION
+          ) {
+            merged.schema_version = SCHEMA_VERSION
+          }
+          if (
+            typeof merged.projectDir !== "string" ||
+            (merged.projectDir as string).length === 0
+          ) {
+            merged.projectDir = projectDir
+          }
+          if (!Array.isArray(merged.scope)) {
+            merged.scope = []
+          }
+          if (!Array.isArray(merged.toolsExecuted)) {
+            merged.toolsExecuted = []
           }
           const validation = validateReportInput(merged)
           if (validation.success) {
             return finalizeReportInputSelection(validation.data, diagnostics, expectedRunId)
           }
+          for (const error of validation.errors) {
+            diagnostics.warn(
+              "REPORT_INPUT_DEDUPED_VALIDATION_FAILED",
+              `${error.field}: ${error.message}`,
+              error.field,
+            )
+          }
         }
       } catch {
         /* deduped file unreadable — fall through to report-input.json */