solidity-argus 0.1.8 → 0.2.0

package/src/create-hooks.ts

@@ -6,20 +6,53 @@ import { createConfigHandler } from "./hooks/config-handler"
 import { createCompactionHook } from "./hooks/compaction-hook"
 import { createToolTrackingHook } from "./hooks/tool-tracking-hook"
 import { createEventHookV2 } from "./hooks/event-hook-v2"
+import { createAgentTracker } from "./hooks/agent-tracker"
+import { createSystemPromptHook } from "./hooks/system-prompt-hook"
 import { safeCreateHook } from "./hooks/safe-create-hook"
-import { createToolOutputTruncator } from "./features/context-monitor"
+import { createContextMonitor, createToolOutputTruncator } from "./features/context-monitor"
+import { createAuditEnforcer } from "./features/audit-enforcer/audit-enforcer"
+import { getTokenBudgetForAgent } from "./hooks/context-budget"
 import { createSessionRecoveryHandler } from "./features/error-recovery"
 import { createToolErrorRecoveryHandler } from "./features/error-recovery"
+import { detectProject } from "./utils/project-detector"
+import type { ProjectConfig } from "./utils/project-detector"
+import { detectAuditArtifacts } from "./utils/audit-artifact-detector"
+import type { ReconContext } from "./hooks/recon-context-builder"
+import { buildReconContextBlock } from "./hooks/recon-context-builder"
+import type { AuditState } from "./state/types"
+
+let latestAgentTracker: ReturnType<typeof createAgentTracker> | undefined
+
+export function getAgentForSession(sessionID: string): string | undefined {
+  return latestAgentTracker?.getAgentForSession(sessionID)
+}
+
+export function isArgusAgent(sessionID: string): boolean {
+  return latestAgentTracker?.isArgusAgent(sessionID) ?? false
+}
 
 export type Hooks = Pick<
   PluginHooks,
   | "config"
+  | "chat.params"
+  | "chat.message"
   | "experimental.chat.system.transform"
   | "experimental.session.compacting"
   | "tool.execute.after"
   | "event"
 >
 
+/**
+ * Creates the hook handlers for the Argus plugin.
+ *
+ * Context Delivery Strategy:
+ * - Prompt: Static agent identity (src/agents/*-prompt.ts) — methodology, personality, tool instructions
+ * - Hook: Dynamic state injection via experimental.chat.system.transform — audit progress, findings, phase
+ * - Skill-load: On-demand knowledge via argus_skill_load tool — vulnerability patterns, protocol knowledge
+ *
+ * The system.transform hook injects dynamic audit context only for Argus-family agents
+ * (argus, sentinel, pythia, scribe). Non-audit agents receive no injection.
+ */
 export function createHooks(args: {
   config: ArgusConfig
   managers: Managers
@@ -28,13 +61,17 @@ export function createHooks(args: {
 }): Hooks {
   const { config, managers, projectDir, isHookEnabled } = args
   const { auditStateManager, backgroundManager } = managers
+  const agentTracker = createAgentTracker()
+  latestAgentTracker = agentTracker
 
-   const sessionRecoveryHandler = createSessionRecoveryHandler(auditStateManager)
-   const toolErrorRecoveryHandler = createToolErrorRecoveryHandler()
-   const outputTruncator = createToolOutputTruncator()
+  const contextMonitor = createContextMonitor()
+  const sessionRecoveryHandler = createSessionRecoveryHandler(auditStateManager)
+  let auditStateGetter: (() => AuditState | null) | undefined
+  const toolErrorRecoveryHandler = createToolErrorRecoveryHandler(() => auditStateGetter?.() ?? null)
+  const outputTruncator = createToolOutputTruncator()
 
   const { hook: eventHook, getAuditState, setAuditState } = createEventHookV2(projectDir, [
-    async ({ type, auditState, setAuditState: setState }) => {
+    async ({ type, sessionId, auditState, setAuditState: setState }) => {
       if (type === "session.created") {
         const recoveredState = await auditStateManager.load()
         if (recoveredState) {
@@ -49,6 +86,9 @@ export function createHooks(args: {
       }
 
       if (type === "session.deleted") {
+        if (sessionId) {
+          agentTracker.clearSession(sessionId)
+        }
         await auditStateManager.reset()
       }
     },
@@ -62,13 +102,50 @@ export function createHooks(args: {
     },
   ])
 
-   const initialState = auditStateManager.get()
-   if (initialState) {
-     setAuditState(initialState)
-   }
+  auditStateGetter = getAuditState
+
+  const initialState = auditStateManager.get()
+  if (initialState) {
+    setAuditState(initialState)
+  }
+
+  const auditEnforcer = createAuditEnforcer()
 
-   const compactionHook = isHookEnabled("compaction")
-    ? safeCreateHook(() => createCompactionHook(getAuditState), "compaction")
+  const systemPromptHook = createSystemPromptHook({
+    getAuditState,
+    getAgentForSession: agentTracker.getAgentForSession,
+    isArgusAgent: agentTracker.isArgusAgent,
+    getContextPressure: (systemText: string) => {
+      const status = contextMonitor.getContextStatus(systemText, getAuditState())
+      return status.usage
+    },
+    getTokenBudget: getTokenBudgetForAgent,
+    getEnforcerReminder: auditEnforcer,
+    getReconBlock: () => buildReconContextBlock({
+      projectConfig: reconProjectConfig,
+      dependencyRisks: reconProjectConfig?.dependencyRisks ?? [],
+      auditArtifacts: detectAuditArtifacts(projectDir),
+    }),
+  })
+
+  let reconProjectConfig: ProjectConfig | null = null
+
+  detectProject(projectDir)
+    .then((config) => {
+      reconProjectConfig = config
+    })
+    .catch(() => {
+      // Silent fallback — audit artifacts remain available
+    })
+
+  const getReconContext = (): ReconContext => ({
+    projectConfig: reconProjectConfig,
+    dependencyRisks: reconProjectConfig?.dependencyRisks ?? [],
+    auditArtifacts: detectAuditArtifacts(projectDir),
+  })
+
+  const compactionHook = isHookEnabled("compaction")
+    ? safeCreateHook(() => createCompactionHook(getAuditState, getReconContext), "compaction")
     : undefined
 
   const toolTrackingHook = isHookEnabled("tool-tracking")
@@ -79,9 +156,17 @@ export function createHooks(args: {
     ? safeCreateHook(() => eventHook, "event")
     : undefined
 
-   return {
-     config: createConfigHandler(config, projectDir),
-     "experimental.chat.system.transform": undefined,
+  return {
+    config: createConfigHandler(config, projectDir),
+    "chat.params": async (input) => {
+      agentTracker.chatParamsHook(input)
+    },
+    "chat.message": async (input) => {
+      agentTracker.chatMessageHook(input)
+    },
+    "experimental.chat.system.transform": async (input, output) => {
+      await systemPromptHook(input, output)
+    },
     "experimental.session.compacting": compactionHook
       ? async (_input, output) => {
           const block = await compactionHook({ summary: output.context.join("\n") })

package/src/create-tools.ts

@@ -8,6 +8,7 @@ import { patternCheckerTool } from "./tools/pattern-checker-tool"
 import { soloditSearchTool } from "./tools/solodit-search-tool"
 import { reportGeneratorTool } from "./tools/report-generator-tool"
 import { syncKnowledgeTool } from "./tools/sync-knowledge-tool"
+import { argusSkillLoadTool } from "./tools/argus-skill-load-tool"
 
 export function createTools(
   config: ArgusConfig,
@@ -18,6 +19,7 @@ export function createTools(
     argus_forge_fuzz: forgeFuzzTool,
     argus_analyze_contract: contractAnalyzerTool,
     argus_check_patterns: patternCheckerTool,
+    argus_skill_load: argusSkillLoadTool,
     argus_generate_report: reportGeneratorTool,
     argus_sync_knowledge: syncKnowledgeTool,
   }

package/src/features/error-recovery/tool-error-recovery.ts

@@ -1,15 +1,60 @@
 import { createLogger } from "../../shared/logger"
+import type { AuditState } from "../../state/types"
 
-const RECOVERY_HINTS: Record<string, string> = {
-  slither: "Install Slither: pip install slither-analyzer",
-  forge: "Install Foundry: curl -L https://foundry.paradigm.xyz | bash && foundryup",
-  solodit: "Check network connectivity or Solodit API status",
-  scvd: "Check SCVD API at https://api.scvd.dev — may be temporarily unavailable",
+type ToolFallbackEntry = {
+  install: string
+  fallback: string
 }
 
-const VIA_IR_HINT = "Project uses via_ir — Slither uses forge-flatten fallback automatically. Ensure forge and solc-select are installed."
+const TOOL_FALLBACKS: Record<string, ToolFallbackEntry> = {
+  slither: {
+    install: "pip install slither-analyzer",
+    fallback:
+      "Slither is unavailable. PROCEED with the audit using `argus_analyze_contract` for structural profiling and `argus_check_patterns` for vulnerability scanning. Note in the final report: \"Automated static analysis (Slither) was unavailable; manual review intensity increased.\"",
+  },
+  forge: {
+    install: "curl -L https://foundry.paradigm.xyz | bash && foundryup",
+    fallback:
+      "Foundry/Forge is unavailable. SKIP automated testing and fuzzing. Verify findings through manual code tracing and static analysis. Note in the final report: \"Dynamic testing (Forge) was unavailable; findings verified via manual analysis.\"",
+  },
+  solodit: {
+    install: "",
+    fallback:
+      "Solodit API is unreachable. PROCEED using `argus_check_patterns` with local vulnerability rules. Note in the final report: \"External vulnerability databases were inaccessible; research limited to local patterns.\"",
+  },
+  scvd: {
+    install: "",
+    fallback:
+      "SCVD API is unavailable. PROCEED with local patterns and Solodit search if available.",
+  },
+}
+
+const VIA_IR_HINT =
+  "Project uses via_ir — Slither uses forge-flatten fallback automatically. Ensure forge and solc-select are installed."
+
+function isToolUnavailable(lowerResult: string): boolean {
+  return (
+    lowerResult.includes("enoent") ||
+    lowerResult.includes("not found") ||
+    lowerResult.includes("not installed")
+  )
+}
+
+function isToolError(lowerResult: string): boolean {
+  return (
+    isToolUnavailable(lowerResult) ||
+    lowerResult.includes("command failed") ||
+    lowerResult.includes("error:")
+  )
+}
+
+function resolveToolBase(tool: string): string {
+  return tool.replace("argus_", "").split("_")[0] ?? ""
+}
 
-export function createToolErrorRecoveryHandler() {
+export function createToolErrorRecoveryHandler(
+  getAuditState?: () => AuditState | null,
+) {
   const logger = createLogger()
 
   return (toolResult: { tool: string; result: string }): string | null => {
@@ -27,22 +72,32 @@ export function createToolErrorRecoveryHandler() {
       return `\n[Argus Recovery Hint] ${VIA_IR_HINT}`
     }
 
-    const isError =
-      lowerResult.includes("enoent") ||
-      lowerResult.includes("not found") ||
-      lowerResult.includes("command failed") ||
-      lowerResult.includes("error:")
+    if (!isToolError(lowerResult)) return null
 
-    if (!isError) return null
+    const toolBase = resolveToolBase(tool)
+    const entry = TOOL_FALLBACKS[toolBase]
+    if (!entry) return null
 
-    const toolBase = tool.replace("argus_", "").split("_")[0] ?? ""
-    const hint = RECOVERY_HINTS[toolBase]
+    const unavailable = isToolUnavailable(lowerResult)
+
+    if (unavailable && getAuditState) {
+      const state = getAuditState()
+      if (state) {
+        state.unavailableTools ??= []
+        if (!state.unavailableTools.includes(toolBase)) {
+          state.unavailableTools.push(toolBase)
+          logger.info(`Recorded ${toolBase} as unavailable — fallback activated`)
+        }
+      }
+    }
 
-    if (hint) {
-      logger.info(`Tool error recovery hint for ${tool}: ${hint}`)
-      return `\n[Argus Recovery Hint] ${hint}`
+    if (unavailable) {
+      logger.info(`Tool unavailable fallback for ${tool}`)
+      return `\n[Argus Fallback] ${entry.fallback}`
     }
 
-    return null
+    const installHint = entry.install ? ` (install: ${entry.install})` : ""
+    logger.info(`Tool error recovery hint for ${tool}`)
+    return `\n[Argus Recovery Hint] ${toolBase} error${installHint}. ${entry.fallback}`
   }
 }

package/src/features/persistent-state/audit-state-manager.ts

@@ -7,7 +7,7 @@ import { createLogger } from "../../shared/logger";
 
 const STATE_FILE_DIR = ".opencode";
 const STATE_FILE_NAME = "argus-state.json";
-const STATE_VERSION = "1";
+const STATE_VERSION = "2";
 
 function isObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
@@ -39,9 +39,11 @@ function isPersistentAuditState(value: unknown): value is PersistentAuditState {
     return false;
   }
 
+  const hasSupportedVersion = value.version === "1" || value.version === "2";
+
   return (
     typeof value.savedAt === "number" &&
-    typeof value.version === "string" &&
+    hasSupportedVersion &&
     typeof value.filePath === "string"
   );
 }
@@ -69,7 +71,17 @@ export function createAuditStateManager(projectDir: string): AuditStateManager {
         return null;
       }
 
-      const { savedAt: _savedAt, version: _version, filePath: _filePath, ...state } = parsed;
+      const { savedAt: _savedAt, version, filePath: _filePath, ...state } = parsed;
+
+      if (version === "1") {
+        if (!state.soloditResults) {
+          state.soloditResults = [];
+        }
+        if (!state.fuzzCounterexamples) {
+          state.fuzzCounterexamples = [];
+        }
+      }
+
       currentState = state;
       return currentState;
     } catch (_error) {
@@ -77,20 +89,31 @@ export function createAuditStateManager(projectDir: string): AuditStateManager {
     }
   }
 
+  let saveInFlight = false;
+
   async function save(state: AuditState): Promise<void> {
     currentState = state;
 
-    const persistentState: PersistentAuditState = {
-      ...state,
-      savedAt: Date.now(),
-      version: STATE_VERSION,
-      filePath: stateFilePath,
-    };
+    if (saveInFlight) return;
+    saveInFlight = true;
 
-    const tempFilePath = `${stateFilePath}.tmp`;
-    await mkdir(dirname(stateFilePath), { recursive: true });
-    await Bun.write(tempFilePath, `${JSON.stringify(persistentState, null, 2)}\n`);
-    await rename(tempFilePath, stateFilePath);
+    try {
+      const persistentState: PersistentAuditState = {
+        ...state,
+        savedAt: Date.now(),
+        version: STATE_VERSION,
+        filePath: stateFilePath,
+      };
+
+      const tempFilePath = `${stateFilePath}.${Date.now()}.tmp`;
+      await mkdir(dirname(stateFilePath), { recursive: true });
+      await Bun.write(tempFilePath, `${JSON.stringify(persistentState, null, 2)}\n`);
+      await rename(tempFilePath, stateFilePath);
+    } catch {
+      // Non-critical: state persistence is best-effort
+    } finally {
+      saveInFlight = false;
+    }
   }
 
   function get(): AuditState {

package/src/hooks/agent-tracker.ts

@@ -0,0 +1,53 @@
+import type { Hooks as PluginHooks } from "@opencode-ai/plugin"
+
+type ChatParamsInput = Parameters<NonNullable<PluginHooks["chat.params"]>>[0] & {
+  agent?: string
+}
+type ChatMessageInput = Parameters<NonNullable<PluginHooks["chat.message"]>>[0]
+
+const ARGUS_FAMILY = new Set(["argus", "sentinel", "pythia", "scribe"])
+
+export type AgentTracker = ReturnType<typeof createAgentTracker>
+
+export function createAgentTracker() {
+  const sessions = new Map<string, string>()
+
+  const trackSession = (sessionID: string, agent?: string): void => {
+    if (!agent) {
+      return
+    }
+
+    sessions.set(sessionID, agent)
+  }
+
+  return {
+    chatParamsHook: (input: ChatParamsInput): void => {
+      trackSession(input.sessionID, input.agent)
+    },
+
+    chatMessageHook: (input: ChatMessageInput): void => {
+      trackSession(input.sessionID, input.agent)
+    },
+
+    getAgentForSession: (sessionID: string): string | undefined => {
+      return sessions.get(sessionID)
+    },
+
+    isArgusAgent: (sessionID: string): boolean => {
+      const agent = sessions.get(sessionID)
+      if (!agent) {
+        return false
+      }
+
+      return ARGUS_FAMILY.has(agent)
+    },
+
+    clearSession: (sessionID: string): void => {
+      sessions.delete(sessionID)
+    },
+
+    getTrackedSessions: (): Map<string, string> => {
+      return sessions
+    },
+  }
+}

package/src/hooks/compaction-hook.ts

@@ -1,50 +1,59 @@
 import type { AuditState, FindingSeverity } from "../state/types"
+import type { ReconContext } from "./recon-context-builder"
+import { buildReconContextBlock } from "./recon-context-builder"
 
-/**
- * Creates a compaction hook that serializes audit state into XML format
- * so findings survive context window compression.
- *
- * The returned hook is called by OpenCode's `experimental.session.compacting`
- * event, receiving `{ summary: string }` and returning the enriched summary.
- */
 export function createCompactionHook(
-  getAuditState: () => AuditState | null
+  getAuditState: () => AuditState | null,
+  getReconContext?: () => ReconContext | null,
 ): (input: { summary: string }) => Promise<string | null> {
   return async (_input: { summary: string }): Promise<string | null> => {
     const state = getAuditState()
-    if (!state) {
-      return null
-    }
 
-    const severityCounts: Record<FindingSeverity, number> = {
-      Critical: 0,
-      High: 0,
-      Medium: 0,
-      Low: 0,
-      Informational: 0,
+    const parts: string[] = []
+
+    if (state) {
+      const severityCounts: Record<FindingSeverity, number> = {
+        Critical: 0,
+        High: 0,
+        Medium: 0,
+        Low: 0,
+        Informational: 0,
+      }
+
+      for (const finding of state.findings) {
+        severityCounts[finding.severity]++
+      }
+
+      const toolNames = state.toolsExecuted.map((t) => t.tool).join(", ")
+      const contracts = state.contractsReviewed.join(", ")
+      const started = new Date(state.startTime).toISOString()
+
+      parts.push(
+        [
+          "<argus-audit-state>",
+          `Phase: ${state.currentPhase}`,
+          `Contracts Reviewed: ${contracts}`,
+          "Findings:",
+          `  Critical: ${severityCounts.Critical}`,
+          `  High: ${severityCounts.High}`,
+          `  Medium: ${severityCounts.Medium}`,
+          `  Low: ${severityCounts.Low}`,
+          `  Informational: ${severityCounts.Informational}`,
+          `Tools Executed: ${toolNames}`,
+          `Started: ${started}`,
+          "</argus-audit-state>",
+        ].join("\n"),
+      )
     }
 
-    for (const finding of state.findings) {
-      severityCounts[finding.severity]++
+    if (getReconContext) {
+      const recon = getReconContext()
+      if (recon) {
+        const reconBlock = buildReconContextBlock(recon)
+        if (reconBlock) parts.push(reconBlock)
+      }
     }
 
-    const toolNames = state.toolsExecuted.map((t) => t.tool).join(", ")
-    const contracts = state.contractsReviewed.join(", ")
-    const started = new Date(state.startTime).toISOString()
-
-    return [
-      "<argus-audit-state>",
-      `Phase: ${state.currentPhase}`,
-      `Contracts Reviewed: ${contracts}`,
-      "Findings:",
-      `  Critical: ${severityCounts.Critical}`,
-      `  High: ${severityCounts.High}`,
-      `  Medium: ${severityCounts.Medium}`,
-      `  Low: ${severityCounts.Low}`,
-      `  Informational: ${severityCounts.Informational}`,
-      `Tools Executed: ${toolNames}`,
-      `Started: ${started}`,
-      "</argus-audit-state>",
-    ].join("\n")
+    return parts.length > 0 ? parts.join("\n") : null
   }
 }

package/src/hooks/config-handler.ts

@@ -93,6 +93,7 @@ export function createConfigHandler(
           argus_forge_fuzz: "allow",
           argus_analyze_contract: "allow",
           argus_check_patterns: "allow",
+          argus_skill_load: "allow",
           skill: "allow",
         },
       },
@@ -104,6 +105,7 @@ export function createConfigHandler(
         permission: {
           argus_solodit_search: "allow",
           argus_check_patterns: "allow",
+          argus_skill_load: "allow",
           skill: "allow",
         },
       },
@@ -114,6 +116,7 @@ export function createConfigHandler(
         prompt: SCRIBE_PROMPT,
         permission: {
           argus_generate_report: "allow",
+          argus_skill_load: "allow",
           skill: "allow",
         },
       },

package/src/hooks/context-budget.ts

@@ -0,0 +1,45 @@
+/**
+ * Context budget allocation for Argus agents.
+ *
+ * Provides per-agent token budgets for system-prompt injection sizing.
+ * Under context pressure (>70%), budgets are reduced by 50% to prevent
+ * context window overflow during long audits.
+ *
+ * Decoupled from system-prompt-hook.ts — consumed by the hook when available.
+ */
+
+const ARGUS_BUDGET = 2000
+const SUBAGENT_BUDGET = 1000
+const PRESSURE_THRESHOLD = 0.70
+const PRESSURE_REDUCTION = 0.5
+
+const ARGUS_AGENTS = new Set(["argus"])
+const SUBAGENTS = new Set(["sentinel", "pythia", "scribe"])
+
+/**
+ * Returns the token budget for a given agent, adjusted for context pressure.
+ *
+ * @param agent - Agent name (e.g. "argus", "sentinel", "pythia", "scribe")
+ * @param contextPressure - Current context usage ratio (0.0–1.0), from ContextMonitor
+ * @returns Token budget in tokens. 0 for non-Argus agents.
+ */
+export function getTokenBudgetForAgent(
+  agent: string,
+  contextPressure: number = 0,
+): number {
+  let budget: number
+
+  if (ARGUS_AGENTS.has(agent)) {
+    budget = ARGUS_BUDGET
+  } else if (SUBAGENTS.has(agent)) {
+    budget = SUBAGENT_BUDGET
+  } else {
+    return 0
+  }
+
+  if (contextPressure > PRESSURE_THRESHOLD) {
+    budget = Math.floor(budget * PRESSURE_REDUCTION)
+  }
+
+  return budget
+}

package/src/hooks/event-hook.ts

@@ -1,5 +1,6 @@
 import type { AuditState } from "../state/types"
 import { createAuditState } from "../state/audit-state"
+import { createLogger } from "../shared/logger"
 
 export type EventHookFn = (input: {
   event: { type: string; sessionId?: string }
@@ -38,8 +39,8 @@ export function createEventHook(projectDir?: string): {
 
       case "session.idle": {
          if (currentAuditState) {
-           console.error(
-             `[argus-state] Session idle — phase: ${currentAuditState.currentPhase}, findings: ${currentAuditState.findings.length}, contracts: ${currentAuditState.contractsReviewed.length}`
+           createLogger().debug(
+             `[state] Session idle — phase: ${currentAuditState.currentPhase}, findings: ${currentAuditState.findings.length}, contracts: ${currentAuditState.contractsReviewed.length}`
            )
          }
          break
@@ -47,8 +48,8 @@ export function createEventHook(projectDir?: string): {
 
       case "session.error": {
         if (currentAuditState) {
-          console.error(
-            `[argus-error] Session error — state snapshot: ${JSON.stringify({
+          createLogger().error(
+            `Session error — state snapshot: ${JSON.stringify({
               sessionId: currentAuditState.sessionId,
               phase: currentAuditState.currentPhase,
               findingsCount: currentAuditState.findings.length,

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

@@ -3,6 +3,7 @@ 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 { createLogger } from "../shared/logger"
 
 export type KnowledgeSyncDependencies = {
   createClient?: (apiUrl: string) => unknown
@@ -18,7 +19,7 @@ function defaultDependencies(): Required<KnowledgeSyncDependencies> {
     syncIncrementalFn: async (client: unknown, indexPath: string) =>
       syncIncremental(client as ScvdClient, indexPath),
     log: (message: string) => {
-       console.error(message)
+       createLogger().info(message)
      },
   }
 }