solidity-argus 0.5.6 → 0.5.8

package/AGENTS.md

@@ -12,33 +12,33 @@ CLI: `argus doctor`, `argus init`, `argus install`.
 
 **Role**: Primary security audit orchestrator
 **Description**: Argus Panoptes, the All-Seeing Guardian. Coordinates full Solidity security audits by dispatching Sentinel (analysis), Pythia (research), Scribe (reporting), and Themis (validation). Follows a rigorous 7-step methodology: Reconnaissance, Automated Scanning, Manual Review, Attack Surface Mapping, Vulnerability Research, Testing & Verification, and Reporting.
-**Model**: anthropic/claude-opus-4-6
+**Model**: anthropic/claude-opus-4-7
 **Tools**: 14 orchestrator-accessible argus_* tools (argus_slither_analyze, argus_analyze_contract, argus_check_patterns, argus_proxy_detection, argus_solodit_search, argus_forge_test, argus_gas_analysis, argus_forge_fuzz, argus_forge_coverage, argus_skill_load, argus_generate_report, argus_record_finding, argus_read_findings, argus_sync_knowledge). `argus_persist_deduped` is reserved for Scribe.
 
 ## sentinel
 
 **Role**: Static analysis and testing specialist
 **Description**: Finds vulnerabilities through Slither static analysis, Foundry testing, fuzzing, and pattern matching. The tactical executor — runs tools, writes PoC tests, and verifies findings. Dispatched by Argus during Automated Scanning and Testing & Verification phases.
-**Model**: anthropic/claude-sonnet-4-6
+**Model**: anthropic/claude-sonnet-4-7
 **Tools**: argus_slither_analyze, argus_forge_test, argus_gas_analysis, argus_forge_fuzz, argus_forge_coverage, argus_analyze_contract, argus_check_patterns, argus_proxy_detection, argus_record_finding, skill
 
 ## pythia
 
 **Role**: Vulnerability researcher
 **Description**: Consults Solodit, SCVD, and the knowledge base to find historical precedents and known attack vectors. Searches 7,769+ real-world audit findings and 51 curated vulnerability pattern files. Dispatched by Argus during Vulnerability Research phase.
-**Model**: anthropic/claude-sonnet-4-6
+**Model**: anthropic/claude-sonnet-4-7
 **Tools**: argus_solodit_search, argus_check_patterns, argus_record_finding, skill
 
 ## scribe
 
 **Role**: Audit report writer
 **Description**: Transforms raw findings into professional markdown audit reports. Produces structured output with severity classifications (Critical/High/Medium/Low/Informational), impact assessments, proof-of-concept steps, and actionable recommendations. Dispatched by Argus only after all analysis is complete.
-**Model**: anthropic/claude-sonnet-4-6
+**Model**: anthropic/claude-sonnet-4-7
 **Tools**: argus_read_findings, argus_persist_deduped, argus_generate_report, skill
 
 ## themis
 
 **Role**: Audit quality gate
-**Description**: Independent cross-validation agent running on GPT-5.4 (different LLM provider for reasoning diversity). Validates pipeline integrity: compares raw findings against Scribe's deduped output and the final report. Performs second-opinion research via Solodit and vulnerability skill checklists. Returns a structured verdict to Argus who makes the final decision. Dispatched by Argus after Scribe completes.
-**Model**: openai/gpt-5.4
+**Description**: Independent cross-validation agent running on GPT-5.5 (different LLM provider for reasoning diversity). Validates pipeline integrity: compares raw findings against Scribe's deduped output and the final report. Performs second-opinion research via Solodit and vulnerability skill checklists. Returns a structured verdict to Argus who makes the final decision. Dispatched by Argus after Scribe completes.
+**Model**: openai/gpt-5.5
 **Tools**: argus_read_findings, argus_solodit_search, argus_check_patterns, argus_skill_load, skill

package/README.md

@@ -65,11 +65,11 @@ Argus will automatically:
 
 | Agent | Role | Model |
 |-------|------|-------|
-| `@argus` | Orchestrator — coordinates the full audit | claude-opus-4-6 |
-| `@sentinel` | Static analysis & testing specialist | claude-sonnet-4-6 |
-| `@pythia` | Vulnerability researcher | claude-sonnet-4-6 |
-| `@scribe` | Audit report writer | claude-sonnet-4-6 |
-| `@themis` | Independent audit quality gate | gpt-5.4 |
+| `@argus` | Orchestrator — coordinates the full audit | claude-opus-4-7 |
+| `@sentinel` | Static analysis & testing specialist | claude-sonnet-4-7 |
+| `@pythia` | Vulnerability researcher | claude-sonnet-4-7 |
+| `@scribe` | Audit report writer | claude-sonnet-4-7 |
+| `@themis` | Independent audit quality gate | gpt-5.5 |
 
 ### @argus — The Orchestrator
 Argus Panoptes is the lead auditor. It follows a 7-step methodology (Reconnaissance, Automated Scanning, Manual Review, Attack Surface Mapping, Vulnerability Research, Testing & Verification, Reporting) and delegates to Sentinel, Pythia, Scribe, and Themis as needed.
@@ -284,11 +284,11 @@ Create `.argus/solidity-argus.jsonc` in your project root. `.opencode/solidity-a
 ```jsonc
 {
   "agents": {
-    "argus": { "model": "anthropic/claude-opus-4-6" },
-    "sentinel": { "model": "anthropic/claude-sonnet-4-6" },
-    "pythia": { "model": "anthropic/claude-sonnet-4-6" },
-    "scribe": { "model": "anthropic/claude-sonnet-4-6" },
-    "themis": { "model": "openai/gpt-5.4" }
+    "argus": { "model": "anthropic/claude-opus-4-7" },
+    "sentinel": { "model": "anthropic/claude-sonnet-4-7" },
+    "pythia": { "model": "anthropic/claude-sonnet-4-7" },
+    "scribe": { "model": "anthropic/claude-sonnet-4-7" },
+    "themis": { "model": "openai/gpt-5.5" }
   },
 
   "tools": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solidity-argus",
-  "version": "0.5.6",
+  "version": "0.5.8",
   "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/argus-prompt.ts

@@ -229,7 +229,7 @@ Task(subagent_type="scribe", prompt="Generate the final audit report for Project
   - **Constraint**: Only invoke Scribe after all analysis and testing are complete.
 
 ### **@themis** (The Quality Gate)
-- **Role**: Independent audit validation using a different LLM provider (GPT-5.4).
+- **Role**: Independent audit validation using a different LLM provider (GPT-5.5).
 - **Tools**: \`argus_read_findings\`, \`argus_solodit_search\`, \`argus_check_patterns\`, \`argus_skill_load\`
 - **Delegation Examples**:
   \`\`\`
@@ -255,7 +255,7 @@ When building the final report or synthesizing findings:
 2. **Secondary source**: Tool transcript text (use only when durable evidence is unavailable or incomplete).
 3. **Never** synthesize findings from ephemeral background transcript retrieval alone if durable state evidence exists.
 4. **Manual-finding durability**: If Argus, Sentinel, or Pythia identifies a finding outside analyzer tool payloads, they must call \
-   \`argus_record_finding\` before proceeding. The JSON payload MUST include \`impact\`, \`recommendation\`, and (for Critical/High) \`proofOfConcept\` fields.
+   \`argus_record_finding\` before proceeding. The JSON payload should include \`impact\`, \`recommendation\`, and \`proofOfConcept\` fields whenever they are known. Missing enrichment is recorded with warnings rather than rejected, but Scribe must enrich final Critical/High findings before reporting.
 5. **Report parity rule**: Scribe must not include findings in \`report_input\` unless they are event-backed (recorded via tools/events).
 
 **Bounded background fan-out**: For deep audits, limit concurrent high-context background delegations to max 2 at a time. Split larger workloads into sequential waves. This prevents retrieval blind spots from simultaneous long-running tasks.
@@ -365,7 +365,7 @@ Your subagents have access to these specialized tools. Know when to delegate eac
   "proofOfConcept": "Steps to reproduce or reference to PoC test"
 }
 \`\`\`
-  - **CRITICAL**: For Critical and High findings, \`impact\`, \`recommendation\`, and \`proofOfConcept\` are MANDATORY. The quality gate will flag findings missing these fields. Preferred field names: \`check\`, \`file\`, \`lines\`. The aliases \`title\`/\`name\` → \`check\` and \`location\` → \`file\` are accepted but canonical names are preferred. Instruct Sentinel and Pythia accordingly when delegating.
+  - **CRITICAL**: For Critical and High final report findings, \`impact\`, \`recommendation\`, and \`proofOfConcept\` are MANDATORY. For any finding with \`source: "slither"\`, preserve the finding even when enrichment is not ready, but add these three fields before final Scribe persistence whenever possible. \`argus_record_finding\` warns on incomplete Slither enrichment instead of dropping the finding. Preferred field names: \`check\`, \`file\`, \`lines\`. The aliases \`title\`/\`name\` → \`check\` and \`location\` → \`file\` are accepted but canonical names are preferred. Instruct Sentinel and Pythia accordingly when delegating.
 
 - **\`argus_sync_knowledge\`**:
   - **Use**: Maintenance.

package/src/agents/pythia-prompt.ts

@@ -103,11 +103,12 @@ You have two primary tools. Master them.
   "lines": [startLine, endLine],
   "source": "manual",
   "impact": "Specific impact based on the historical precedent (e.g., 'Total vault drain via flash loan, similar to $X loss in Protocol Y')",
-  "recommendation": "Specific mitigation from the precedent audit report"
+  "recommendation": "Specific mitigation from the precedent audit report",
+  "proofOfConcept": "Steps to reproduce, exploit sketch, or reference to the historical exploit/audit evidence"
 }
 \`\`\`
 
-**CRITICAL**: For Critical and High findings, \`impact\` and \`recommendation\` are MANDATORY. The quality gate will flag findings missing these fields. Use your Solodit research to write specific, precedent-backed impact and recommendation text — not generic placeholders.
+**CRITICAL**: For Critical and High final report findings, \`impact\`, \`recommendation\`, and \`proofOfConcept\` are MANDATORY. \`argus_record_finding\` preserves incomplete findings with warnings rather than dropping them, but Scribe must enrich them before final reporting. Use your Solodit research to write specific, precedent-backed impact, recommendation, and proof-of-concept text — not generic placeholders.
 
 **Interpretation**:
 - A finding is not report-ready until it has been recorded through this tool.
@@ -124,7 +125,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/agents/sentinel-prompt.ts

@@ -151,7 +151,7 @@ You have access to a specific set of tools. Use them effectively.
 }
 \`\`\`
 
-**CRITICAL**: For Critical and High findings, \`impact\`, \`recommendation\`, and \`proofOfConcept\` are MANDATORY. The quality gate will flag findings missing these fields. Do not use generic placeholders — be specific to the vulnerability.
+**CRITICAL**: For Critical and High findings, \`impact\`, \`recommendation\`, and \`proofOfConcept\` are MANDATORY. For any finding with \`source: "slither"\`, preserve the finding even when enrichment is not ready, but add these three fields before final Scribe persistence whenever possible. \`argus_record_finding\` warns on incomplete Slither enrichment instead of dropping the finding. Do not use generic placeholders — be specific to the vulnerability.
 
 **Interpretation**:
 - Recording is mandatory before handing findings to Argus for final synthesis.

package/src/agents/themis-prompt.ts

@@ -5,7 +5,7 @@ export const THEMIS_PROMPT = `You are **Themis**, the Quality Gate of Argus Pano
 You are the final validation and review agent in the audit pipeline. You do not run the full audit from scratch and you do not write the final report. You verify that the pipeline output is complete, consistent, and defensible.
 
 Model context:
-- You run on **OpenAI GPT-5.4-pro**.
+- You run on **OpenAI GPT-5.5**.
 - This is intentionally a different provider than the other Argus agents (Claude) to increase reasoning diversity for final quality checks.
 
 Your core responsibilities are:

package/src/cli/commands/doctor.ts

@@ -1,5 +1,6 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs"
-import { basename, dirname, extname, join } from "node:path"
+import { homedir } from "node:os"
+import { basename, dirname, extname, join, resolve } from "node:path"
 import { loadArgusConfig } from "../../config/loader"
 import type { ArgusConfig } from "../../config/types"
 import { createLogger } from "../../shared/logger"
@@ -133,6 +134,143 @@ export function buildSkillHealthReport(
   }
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Install-drift detection
+//
+// OpenCode's plugin resolver walks up the filesystem looking up `node_modules`
+// directories. A stale copy of solidity-argus hoisted to a higher-precedence
+// location (typically `~/.cache/opencode/node_modules/solidity-argus`) will
+// SHADOW the canonical install under `~/.cache/opencode/packages/...`. The
+// shadowing install is loaded silently, leading to confusing failures like
+// `undefined is not an object (evaluating 'result.toLowerCase')` on every MCP
+// call (older versions lacked defensive guards in `tool.execute.after`).
+//
+// This check enumerates known install locations and flags drift.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type ArgusInstallSource =
+  | "current"
+  | "hoisted-cache"
+  | "package-cache"
+  | "user-config"
+  | "project-local"
+
+export type ArgusInstall = {
+  source: ArgusInstallSource
+  path: string
+  version: string | null
+}
+
+export type InstallDriftReport = {
+  current: ArgusInstall | null
+  installs: ArgusInstall[]
+  errors: string[]
+  warnings: string[]
+}
+
+function readPackageVersion(packageRoot: string): string | null {
+  try {
+    const raw = readFileSync(join(packageRoot, "package.json"), "utf8")
+    const parsed = JSON.parse(raw) as { version?: unknown }
+    return typeof parsed.version === "string" ? parsed.version : null
+  } catch {
+    return null
+  }
+}
+
+function getCurrentArgusInstall(): ArgusInstall | null {
+  // doctor.ts lives at <packageRoot>/src/cli/commands/doctor.ts
+  const packageRoot = resolve(import.meta.dir, "../../..")
+  if (!existsSync(join(packageRoot, "package.json"))) return null
+  const version = readPackageVersion(packageRoot)
+  return { source: "current", path: packageRoot, version }
+}
+
+export function enumerateArgusInstallCandidates(
+  cwd: string,
+  home: string,
+): Array<{ source: ArgusInstallSource; path: string }> {
+  return [
+    {
+      source: "hoisted-cache",
+      path: join(home, ".cache", "opencode", "node_modules", "solidity-argus"),
+    },
+    {
+      source: "package-cache",
+      path: join(
+        home,
+        ".cache",
+        "opencode",
+        "packages",
+        "solidity-argus@latest",
+        "node_modules",
+        "solidity-argus",
+      ),
+    },
+    {
+      source: "user-config",
+      path: join(home, ".config", "opencode", "node_modules", "solidity-argus"),
+    },
+    {
+      source: "project-local",
+      path: join(cwd, "node_modules", "solidity-argus"),
+    },
+  ]
+}
+
+function findArgusInstalls(cwd: string, home: string): ArgusInstall[] {
+  const installs: ArgusInstall[] = []
+  for (const { source, path } of enumerateArgusInstallCandidates(cwd, home)) {
+    if (existsSync(path)) {
+      installs.push({ source, path, version: readPackageVersion(path) })
+    }
+  }
+  return installs
+}
+
+export function detectInstallDrift(
+  current: ArgusInstall | null,
+  installs: ArgusInstall[],
+): { errors: string[]; warnings: string[] } {
+  const errors: string[] = []
+  const warnings: string[] = []
+
+  const hoisted = installs.find((i) => i.source === "hoisted-cache")
+  const pkgCache = installs.find((i) => i.source === "package-cache")
+
+  // Highest-confidence error: hoisted cache shadows the canonical cache with a
+  // DIFFERENT version. OpenCode will load the wrong one.
+  if (hoisted && pkgCache && hoisted.version !== pkgCache.version) {
+    errors.push(
+      `Stale install shadowing canonical version:\n` +
+        `    ${hoisted.path} (v${hoisted.version ?? "unknown"})\n` +
+        `    shadows ${pkgCache.path} (v${pkgCache.version ?? "unknown"}).\n` +
+        `    OpenCode will load v${hoisted.version ?? "unknown"} instead of v${pkgCache.version ?? "unknown"}.\n` +
+        `    Fix: rm -rf "${hoisted.path}"`,
+    )
+    return { errors, warnings }
+  }
+
+  // Lower-confidence: hoisted install drifts from the version the doctor CLI
+  // is itself running as (typical when the user upgraded via bunx/opencode).
+  if (hoisted && current?.version && hoisted.version && hoisted.version !== current.version) {
+    warnings.push(
+      `Possible stale install (drift from running version):\n` +
+        `    ${hoisted.path} (v${hoisted.version}) differs from current (v${current.version}).\n` +
+        `    Fix: rm -rf "${hoisted.path}"`,
+    )
+  }
+
+  return { errors, warnings }
+}
+
+export function buildInstallDriftReport(cwd: string, home: string): InstallDriftReport {
+  const current = getCurrentArgusInstall()
+  const installs = findArgusInstalls(cwd, home)
+  const { errors, warnings } = detectInstallDrift(current, installs)
+  return { current, installs, errors, warnings }
+}
+
 const NON_SKILL_FILENAMES = new Set(["README.md", "INVENTORY.md", "CHANGELOG.md", "LICENSE.md"])
 
 function scanMarkdownFiles(dir: string, maxDepth = 8): string[] {
@@ -237,6 +375,22 @@ export const doctorCommand: CliCommand = {
       cliOutput.log(`${YELLOW}⚠${RESET} Project: no Solidity project detected`)
     }
 
+    const driftReport = buildInstallDriftReport(cwd, homedir())
+    if (driftReport.errors.length === 0 && driftReport.warnings.length === 0) {
+      const versionStr = driftReport.current?.version
+        ? ` (current: v${driftReport.current.version})`
+        : ""
+      cliOutput.log(`${GREEN}✓${RESET} Install drift: none detected${versionStr}`)
+    } else {
+      for (const err of driftReport.errors) {
+        cliOutput.log(`${RED}✗${RESET} Install drift: ${err}`)
+        hasFailure = true
+      }
+      for (const warn of driftReport.warnings) {
+        cliOutput.log(`${YELLOW}⚠${RESET} Install drift: ${warn}`)
+      }
+    }
+
     if (projectType === "foundry" && detectViaIr(cwd)) {
       cliOutput.log(
         `${YELLOW}⚠${RESET} via_ir: enabled in foundry.toml — Slither will use flatten fallback`,

package/src/cli/commands/install.ts

@@ -1,57 +1,101 @@
-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/constants/defaults.ts

@@ -1,9 +1,9 @@
 export const DEFAULT_MODELS = {
-  argus: "anthropic/claude-opus-4-6",
-  sentinel: "anthropic/claude-sonnet-4-6",
-  pythia: "anthropic/claude-sonnet-4-6",
-  scribe: "anthropic/claude-sonnet-4-6",
-  themis: "openai/gpt-5.4",
+  argus: "anthropic/claude-opus-4-7",
+  sentinel: "anthropic/claude-sonnet-4-7",
+  pythia: "anthropic/claude-sonnet-4-7",
+  scribe: "anthropic/claude-sonnet-4-7",
+  themis: "openai/gpt-5.5",
 } as const
 
 export const DEFAULT_STEPS = 50 as const

package/src/create-hooks.ts

@@ -14,7 +14,7 @@ import {
   releaseEventSink,
 } 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 +874,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 +903,7 @@ export function createHooks(args: {
 
               if (hasNewFinalization && finalizationResult.runId.length > 0) {
                 try {
-                  await materializeFindingsForRun(
+                  await runMaterializeFindings(
                     finalizationResult.runId,
                     projectDir,
                     eventSessionId,
@@ -1093,12 +1076,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,13 @@ 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 +85,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/features/persistent-state/run-finalizer.ts

@@ -83,6 +83,54 @@ function asRecord(value: unknown): Record<string, unknown> | null {
   return null
 }
 
+function isGenerateReportCompletion(event: AuditEvent): boolean {
+  if (event.type !== "tool.completed") return false
+  const payload = asRecord(event.payload)
+  if (!payload) return false
+  return payload.tool === "argus_generate_report" || payload.name === "argus_generate_report"
+}
+
+async function collectReportCompletenessErrors(events: AuditEvent[]): Promise<string[]> {
+  const errors: string[] = []
+  const reportEvents = events.filter(isGenerateReportCompletion)
+
+  for (const event of reportEvents) {
+    const payload = asRecord(event.payload)
+    const filePath = payload?.filePath
+    if (typeof filePath !== "string" || filePath.length === 0) continue
+
+    try {
+      const report = await Bun.file(filePath).text()
+      if (report.includes("## ⚠ Completeness Warning")) {
+        errors.push("generated report contains Completeness Warning")
+      }
+    } catch {
+      // Missing report files are handled by report-generation/tool-tracking gates.
+    }
+  }
+
+  return errors
+}
+
+function collectReportQualityGateErrors(events: AuditEvent[]): string[] {
+  const errors: string[] = []
+  const reportEvents = events.filter(isGenerateReportCompletion)
+
+  for (const event of reportEvents) {
+    const payload = asRecord(event.payload)
+    const qualityGates = asRecord(payload?.qualityGates)
+    if (qualityGates?.passed !== false) continue
+
+    const violations = Array.isArray(qualityGates.violations)
+      ? qualityGates.violations.filter((entry): entry is string => typeof entry === "string")
+      : []
+    const details = violations.length > 0 ? `: ${violations.join("; ")}` : ""
+    errors.push(`generated report failed quality gates${details}`)
+  }
+
+  return errors
+}
+
 function collectParentChildIntegrityErrors(events: AuditEvent[]): string[] {
   const errors: string[] = []
   const parentByChild = new Map<string, string>()
@@ -257,17 +305,25 @@ export async function finalizeRun(
   const hasEventsAfterExistingFinalization =
     existingResult !== null && existingResult.finalizedIndex < events.length - 1
   if (existingResult?.invariantsPassed && !hasEventsAfterExistingFinalization) {
-    return {
-      success: existingResult.success,
-      invariantsPassed: existingResult.invariantsPassed,
-      errors: existingResult.errors,
-      warnings: existingResult.warnings,
-      runId: existingResult.runId,
-      timestamp: existingResult.timestamp,
+    const reportErrors = [
+      ...(await collectReportCompletenessErrors(events)),
+      ...collectReportQualityGateErrors(events),
+    ]
+    if (reportErrors.length === 0) {
+      return {
+        success: existingResult.success,
+        invariantsPassed: existingResult.invariantsPassed,
+        errors: existingResult.errors,
+        warnings: existingResult.warnings,
+        runId: existingResult.runId,
+        timestamp: existingResult.timestamp,
+      }
     }
   }
 
   const { errors, warnings } = collectInvariantErrors(events)
+  errors.push(...(await collectReportCompletenessErrors(events)))
+  errors.push(...collectReportQualityGateErrors(events))
   const invariantsPassed = errors.length === 0
   const sessionId = events.at(-1)?.session_id ?? ""
 

package/src/hooks/config-handler.ts

@@ -185,7 +185,7 @@ export function createConfigHandler(
         mode: "subagent",
         model: argusConfig.agents?.themis?.model ?? DEFAULT_MODELS.themis,
         steps: argusConfig.agents?.themis?.steps ?? DEFAULT_STEPS,
-        description: "Audit quality gate — independent cross-validation (GPT-5.4)",
+        description: "Audit quality gate — independent cross-validation (GPT-5.5)",
         prompt: THEMIS_PROMPT,
         permission: {
           argus_read_findings: "allow",

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/persist-deduped-tool.ts

@@ -85,7 +85,7 @@ export const persistDedupedTool = tool({
     deduped_findings: tool.schema
       .string()
       .describe(
-        "Serialized JSON array of deduplicated and enriched findings. Each finding should have: check, severity, confidence, description, file, lines, source, impact, recommendation.",
+        "Serialized JSON array of deduplicated and enriched findings. Each finding should have: check, severity, confidence, description, file, lines, source, impact, recommendation, proofOfConcept.",
       ),
   },
   async execute(args, context) {

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

@@ -16,13 +16,20 @@ 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
+  enrichment_warnings?: string[]
+  enrichment_hint?: string
 }
 
 type ParseResult = { ok: true; data: Record<string, unknown>[] } | { ok: false; error: string }
@@ -74,6 +81,16 @@ function errorResponse(error: string): string {
   })
 }
 
+function collectMissingEnrichmentFields(
+  finding: ReturnType<typeof normalizeToCanonicalFinding>["data"],
+): string[] {
+  const missing: string[] = []
+  if (!isNonEmptyString(finding.impact)) missing.push("impact")
+  if (!isNonEmptyString(finding.recommendation)) missing.push("recommendation")
+  if (!isNonEmptyString(finding.proofOfConcept)) missing.push("proofOfConcept")
+  return missing
+}
+
 export async function executeRecordFinding(
   args: RecordFindingArgs,
   context: ToolContext,
@@ -155,16 +172,21 @@ export async function executeRecordFinding(
     return errorResponse(`Failed to record finding(s): ${errors.join("; ")}`)
   }
 
-  // Warn when Critical/High findings are missing enrichment fields
+  // Warn when report-quality enrichment is missing without dropping findings.
   const enrichmentWarnings: string[] = []
   const HIGH_SEVERITIES = new Set(["Critical", "High"])
   for (const f of findings) {
-    if (!HIGH_SEVERITIES.has(f.severity)) continue
-    const missing: string[] = []
-    if (!f.impact) missing.push("impact")
-    if (!f.recommendation) missing.push("recommendation")
-    if (!f.proofOfConcept) missing.push("proofOfConcept")
+    const missing = collectMissingEnrichmentFields(f)
     if (missing.length > 0) {
+      if (f.source === "slither") {
+        enrichmentWarnings.push(
+          `[${f.severity}] Slither finding ${f.check} in ${f.file} is missing: ${missing.join(", ")}. The finding was recorded, but Scribe must enrich it before final reporting.`,
+        )
+        continue
+      }
+
+      if (!HIGH_SEVERITIES.has(f.severity)) continue
+
       enrichmentWarnings.push(
         `[${f.severity}] ${f.check} in ${f.file} is missing: ${missing.join(", ")}. Quality gate will flag this.`,
       )
@@ -178,10 +200,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.",
@@ -189,7 +216,7 @@ export async function executeRecordFinding(
       ? {
           enrichment_warnings: enrichmentWarnings,
           enrichment_hint:
-            "Critical and High findings MUST include impact, recommendation, and proofOfConcept fields. Re-submit with these fields to pass the quality gate.",
+            "Critical and High findings MUST include impact, recommendation, and proofOfConcept fields. Slither findings should include all three fields before Scribe persists deduped findings; incomplete Slither records are preserved but will be flagged by report quality gates if not enriched downstream.",
         }
       : {}),
   }
@@ -205,13 +232,13 @@ export const recordFindingTool = tool({
       .string()
       .optional()
       .describe(
-        'Serialized JSON object for a single finding. Required fields: check (string, e.g. "reentrancy-eth"), severity (Critical|High|Medium|Low|Informational), confidence (High|Medium|Low), description (string), file (relative path, e.g. "src/Vault.sol"), lines ([startLine, endLine] tuple), source ("manual"). Optional: impact, recommendation, proofOfConcept (mandatory for Critical/High).',
+        'Serialized JSON object for a single finding. Required fields: check (string, e.g. "reentrancy-eth"), severity (Critical|High|Medium|Low|Informational), confidence (High|Medium|Low), description (string), file (relative path, e.g. "src/Vault.sol"), lines ([startLine, endLine] tuple), source ("manual"|"slither"|"pattern"|"scvd"|"solodit"|"fuzz"). Optional: impact, recommendation, proofOfConcept (mandatory for Critical/High final report findings; strongly recommended for Slither-source findings before Scribe persistence).',
       ),
     findings: tool.schema
       .string()
       .optional()
       .describe(
-        "Serialized JSON array of finding objects. Each object requires the same fields as the finding parameter: check, severity, confidence, description, file, lines, source. Aliases title/name → check and location → file are accepted but canonical names are preferred.",
+        "Serialized JSON array of finding objects. Each object requires the same fields as the finding parameter: check, severity, confidence, description, file, lines, source. impact, recommendation, and proofOfConcept are mandatory for Critical/High final report findings and strongly recommended for Slither-source findings before Scribe persistence. Aliases title/name → check and location → file are accepted but canonical names are preferred.",
       ),
   },
   async execute(args, context) {

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,59 @@ 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 */
@@ -776,6 +853,13 @@ function sortFindingsDeterministically(findings: Finding[]): Finding[] {
   return [...findings].sort(compareFindingsDeterministically)
 }
 
+function hasDedupLineage(findings: Finding[]): boolean {
+  return findings.some((finding) => {
+    const observationIds = (finding as { observation_ids?: unknown }).observation_ids
+    return Array.isArray(observationIds) && observationIds.length > 0
+  })
+}
+
 export function validateReportQuality(
   findings: Finding[],
   policy: QualityGatePolicy,
@@ -1072,7 +1156,7 @@ export async function executeReportGeneration(
   deps: ReportGenerationDependencies = {},
 ): Promise<ReportGenerationResult> {
   const includeExecutiveSummary = args.include_executive_summary ?? true
-  const threshold = args.severity_threshold ?? "low"
+  const threshold = args.severity_threshold ?? "informational"
   const qualityGatePolicy = args.quality_gate_policy ?? "warn"
   const toolCoveragePolicy = args.tool_coverage_policy ?? "enforce"
   const expectedRunId = resolveExpectedRunId(args, context, deps)
@@ -1148,7 +1232,24 @@ export async function executeReportGeneration(
 
     const eventFindings = dedupeFindingsForFinalOutput(projectFindings(events))
     const inputFindings = dedupeFindingsForFinalOutput(reportInput.findings)
-    const parity = compareIssueFingerprintSets(eventFindings, inputFindings)
+    const hasLineage = hasDedupLineage(reportInput.findings)
+    const shouldCheckParity = eventFindings.length === inputFindings.length || hasLineage
+    const parity = shouldCheckParity
+      ? compareIssueFingerprintSets(eventFindings, inputFindings)
+      : { missing: [], extra: [], matches: true }
+
+    if (!shouldCheckParity) {
+      const unverifiableSummary = `event_findings=${eventFindings.length}, report_findings=${inputFindings.length}`
+      if (preflightPolicy === "strict-fail") {
+        throw new Error(
+          `Preflight failed (strict-fail): finding parity not verifiable (${unverifiableSummary}; missing observation_ids)`,
+        )
+      }
+
+      warningBullets.push(
+        `- Finding parity not verifiable: ${unverifiableSummary}; deduped findings must include observation_ids to prove merged observations were preserved`,
+      )
+    }
 
     if (!parity.matches) {
       const mismatchSummary = `missing=${parity.missing.length}, extra=${parity.extra.length}`