solidity-argus 0.1.8 → 0.3.0

package/skills/vulnerability-patterns/unexpected-ecrecover-null-address/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: unexpected-ecrecover-null-address
-description: - Contract uses `ecrecover` directly (not via OpenZeppelin's ECDSA library)
+description: '- Contract uses `ecrecover` directly (not via OpenZeppelin''s ECDSA library)'
+pattern_category: signature
+detection_rules:
+  - regex: 'ecrecover\([^\n]*\)'
+    severity: Medium
+    confidence: Medium
+    swc: SWC-117
+    description: Raw ecrecover call that requires explicit address(0) handling
 ---
 <!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
 

package/skills/vulnerability-patterns/uninitialized-storage-pointer/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: uninitialized-storage-pointer
-description: - Solidity version <0.5.0
+description: '- Solidity version <0.5.0'
+pattern_category: logic-error
+detection_rules:
+  - regex: 'storage\b'
+    severity: Low
+    confidence: Low
+    swc: SWC-109
+    description: Storage data-location usage that may indicate legacy pointer hazards
 ---
 <!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
 

package/skills/vulnerability-patterns/unsafe-erc20-transfers/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: unsafe-erc20-transfers
+description: Unsafe ERC20 transfer and approve calls that silently fail on non-standard tokens.
+category: vulnerability-pattern
+pattern_category: token-standard
+source_url: https://github.com/bailsec/BailSec
+source_license: CC0
+imported_at: "2026-02-20T00:00:00Z"
+detection_rules:
+  - regex: '\.transfer\([^)]+\)\s*;'
+    severity: Medium
+    confidence: Medium
+    description: Direct ERC20 transfer without SafeERC20 wrapper — may silently fail on non-standard tokens
+  - regex: '\.approve\([^)]+\)\s*;'
+    severity: Medium
+    confidence: Medium
+    description: Direct ERC20 approve without SafeERC20 wrapper — may silently fail on USDT-like tokens
+  - regex: 'IERC20\([^)]+\)\.transfer'
+    severity: Medium
+    confidence: High
+    description: Interface-cast ERC20 transfer without safe wrapper — return value not checked
+  - regex: 'IERC20\([^)]+\)\.approve'
+    severity: Medium
+    confidence: High
+    description: Interface-cast ERC20 approve without safe wrapper — return value not checked
+---
+
+<!-- Source: BailSec audit reports (CC0) -->
+<!-- Extracted via audit-ingest pipeline from 4 independent protocol audits -->
+
+# Unsafe ERC20 Transfer and Approve Calls
+
+## Overview
+
+The standard ERC20 interface specifies that `transfer()`, `transferFrom()`, and `approve()` return a `bool` indicating success. However, many widely-used tokens deviate from this standard:
+
+- **USDT** does not return a boolean on `transfer`/`approve`
+- **BNB**, **OMG** have missing return values
+- Some tokens return `false` on failure instead of reverting
+
+Contracts that call these functions directly (without SafeERC20) either:
+1. **Ignore the return value** → silent failure, tokens not actually transferred
+2. **Expect a boolean return** → revert on tokens that don't return one (like USDT)
+
+**Severity:** Low to Medium
+
+**Prevalence:** Found in 4 independent BailSec audits: Hypertrade V3 Core, Meuna, Robinos, SwapX Exchange.
+
+---
+
+## Vulnerable Pattern
+
+```solidity
+// VULNERABLE: Direct transfer — no return value check
+function withdraw(address token, uint256 amount) external {
+    IERC20(token).transfer(msg.sender, amount);
+    // If token returns false instead of reverting, this silently fails
+    // If token doesn't return bool (USDT), this reverts unexpectedly
+    balances[msg.sender] -= amount;  // State updated even if transfer failed!
+}
+
+// VULNERABLE: Direct approve — breaks with USDT
+function approveSpender(address token, address spender, uint256 amount) external {
+    IERC20(token).approve(spender, amount);
+    // USDT requires setting allowance to 0 before changing to non-zero
+    // Direct approve also doesn't handle missing return values
+}
+```
+
+## Secure Pattern
+
+```solidity
+import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+
+using SafeERC20 for IERC20;
+
+// SECURE: SafeERC20 handles all non-standard token behaviors
+function withdraw(address token, uint256 amount) external {
+    IERC20(token).safeTransfer(msg.sender, amount);
+    // Reverts on failure for ALL token types
+    balances[msg.sender] -= amount;
+}
+
+// SECURE: forceApprove handles USDT's approve quirk
+function approveSpender(address token, address spender, uint256 amount) external {
+    IERC20(token).forceApprove(spender, amount);
+    // Sets to 0 first if needed (USDT), handles missing return values
+}
+```
+
+## Impact
+
+- **Silent failure**: Token transfer returns `false` but contract proceeds as if successful — leads to accounting mismatch
+- **Unexpected revert**: Contract fails on widely-used tokens (USDT, BNB) that don't conform to standard return types
+- **Stuck funds**: Approve fails on USDT when changing non-zero allowance without zeroing first
+- **Loss of funds**: State changes applied after a silently failed transfer result in fund loss
+
+## Affected Token Examples
+
+| Token | Issue | Consequence |
+|-------|-------|-------------|
+| USDT | No bool return on transfer/approve | Reverts if caller expects bool return |
+| USDT | Requires approve(0) before approve(N) | Approve fails for non-zero to non-zero |
+| BNB | Missing return value | Reverts on standard interface call |
+| OMG | Missing return value | Reverts on standard interface call |
+| ZRX | Returns false on failure (no revert) | Silent failure if return unchecked |
+
+## Detection Checklist
+
+1. Does the contract use `IERC20.transfer()` or `IERC20.transferFrom()` directly?
+2. Is OpenZeppelin's `SafeERC20` imported and applied via `using SafeERC20 for IERC20`?
+3. Are `safeTransfer`, `safeTransferFrom`, and `forceApprove` used instead of raw calls?
+4. Does the contract need to support USDT or other non-standard tokens?
+
+## Relationship to Other Patterns
+
+- **unchecked-return-values**: Covers low-level `.call()`, `.send()`, `.delegatecall()` return values — different from ERC20 interface returns
+- **weird-tokens**: Broader reference covering all non-standard token behaviors — this skill focuses specifically on the transfer/approve safety wrapper pattern
+- **fee-on-transfer-tokens**: Covers amount mismatch due to transfer fees — complementary to this pattern
+
+## Remediation
+
+1. **Use SafeERC20**: Import and apply `using SafeERC20 for IERC20` for all ERC20 interactions
+2. **Use forceApprove**: Replace `approve()` with `forceApprove()` to handle USDT
+3. **Audit token list**: Verify which tokens the protocol supports and test with non-standard ones
+4. **Add integration tests**: Test deposit/withdraw flows with USDT, USDC, and at least one missing-return-value token
+
+## References
+
+- [OpenZeppelin SafeERC20](https://docs.openzeppelin.com/contracts/5.x/api/token/erc20#SafeERC20)
+- [Weird ERC20 — Missing Return Values](https://github.com/d-xo/weird-erc20#missing-return-values)
+- BailSec audit reports: Hypertrade V3 Core, Meuna, Robinos, SwapX Exchange

package/skills/vulnerability-patterns/unsafe-low-level-call/SKILL.md

@@ -1,6 +1,17 @@
 ---
 name: unsafe-low-level-call
-description: - Contract uses `.call()`, `.delegatecall()`, `.staticcall()`, or `.send()` for external interactions
+description: '- Contract uses `.call()`, `.delegatecall()`, `.staticcall()`, or `.send()` for external interactions'
+pattern_category: logic-error
+detection_rules:
+  - regex: '\.call\('
+    severity: Medium
+    confidence: Medium
+    swc: SWC-104
+    description: Low-level call usage requiring strict target and return-value checks
+  - regex: '\.delegatecall\('
+    severity: High
+    confidence: Medium
+    description: delegatecall usage with elevated storage-context risk
 ---
 <!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
 

package/skills/vulnerability-patterns/unsecure-signatures/SKILL.md

@@ -1,6 +1,17 @@
 ---
 name: unsecure-signatures
-description: - Contract uses ECDSA signatures for authorization, authentication, or message verification
+description: '- Contract uses ECDSA signatures for authorization, authentication, or message verification'
+pattern_category: signature
+detection_rules:
+  - regex: 'ecrecover\(\s*'
+    severity: Medium
+    confidence: Medium
+    swc: SWC-117
+    description: Signature recovery path needing malleability and null-address protections
+  - regex: 'keccak256\(abi\.encodePacked\('
+    severity: Medium
+    confidence: Low
+    description: Packed hash construction in signature domain may enable collisions
 ---
 <!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
 

package/skills/vulnerability-patterns/unsupported-opcodes/SKILL.md

@@ -1,6 +1,16 @@
 ---
 name: unsupported-opcodes
-description: - Contract is intended for deployment on an EVM-compatible chain other than Ethereum mainnet (zkSync Era, Arbitrum, Optimism, Polygon, BNB Chain, etc.)
+description: '- Contract is intended for deployment on an EVM-compatible chain other than Ethereum mainnet (zkSync Era, Arbitrum, Optimism, Polygon, BNB Chain, etc.)'
+pattern_category: logic-error
+detection_rules:
+  - regex: 'selfdestruct\('
+    severity: Medium
+    confidence: High
+    description: Opcode/functionality that can be unsupported or altered on target chains
+  - regex: '\.transfer\('
+    severity: Low
+    confidence: Low
+    description: transfer stipend behavior may break on non-mainnet EVMs
 ---
 <!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
 

package/skills/vulnerability-patterns/unused-variables/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: unused-variables
-description: - Contract declares state variables, local variables, function parameters, or imports that are never referenced
+description: '- Contract declares state variables, local variables, function parameters, or imports that are never referenced'
+pattern_category: logic-error
+detection_rules:
+  - regex: '(uint256|address|bool|bytes|string|mapping)\s+\w+\s*;'
+    severity: Informational
+    confidence: Low
+    swc: SWC-131
+    description: Declaration pattern that can surface potentially unused variables
 ---
 <!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
 

package/skills/vulnerability-patterns/use-of-deprecated-functions/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: use-of-deprecated-functions
-description: - Contract uses Solidity functions, keywords, or language features that have been deprecated or removed
+description: '- Contract uses Solidity functions, keywords, or language features that have been deprecated or removed'
+pattern_category: logic-error
+detection_rules:
+  - regex: '(suicide|sha3|block\.blockhash|msg\.gas)\('
+    severity: Informational
+    confidence: High
+    swc: SWC-111
+    description: Deprecated Solidity built-ins or aliases
 ---
 <!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
 

package/skills/vulnerability-patterns/weak-sources-randomness/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: weak-sources-randomness
-description: - Contract generates \"random\" values using on-chain data: `block.timestamp`, `blockhash`, `block.difficulty` / `block.prevrandao`, `block.number`, or combinations thereof
+description: '- Contract generates "random" values using on-chain data: `block.timestamp`, `blockhash`, `block.difficulty` / `block.prevrandao`, `block.number`, or combinations thereof'
+pattern_category: logic-error
+detection_rules:
+  - regex: '(block\.timestamp|block\.prevrandao|block\.difficulty|blockhash)\b'
+    severity: Medium
+    confidence: Medium
+    swc: SWC-120
+    description: On-chain attributes used as randomness source
 ---
 <!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
 

package/skills/vulnerability-patterns/weird-tokens/SKILL.md

@@ -1,6 +1,16 @@
 ---
 name: weird-tokens
 description: Non-standard ERC20 behaviors, integration pitfalls, and token-handling safeguards.
+pattern_category: token-standard
+detection_rules:
+  - regex: 'IERC20\('
+    severity: Informational
+    confidence: Low
+    description: ERC20 integration point where non-standard token behavior may break assumptions
+  - regex: '\.approve\('
+    severity: Low
+    confidence: Low
+    description: approve usage requires allowance race and non-standard token handling checks
 ---
 <!-- Source: DeFiFoFum/fofum-solidity-skills (MIT) -->
 

package/skills/vulnerability-patterns/zero-address-misconfiguration/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: zero-address-misconfiguration
+description: "Critical addresses are set to address(0), causing hard reverts, fund loss paths, or permanently broken flows."
+category: vulnerability-pattern
+pattern_category: access-control
+source_url: "https://github.com/bailsec/BailSec"
+source_license: "CC0"
+imported_at: "2025-02-20T00:00:00Z"
+detection_rules:
+  - regex: "(set|update|initialize|constructor).*(address|receiver|collector|team).*=\\s*address\\(0\\)"
+    severity: "High"
+    description: "Administrative path allows writing a critical address to zero"
+  - regex: "transfer\\(address\\(0\\)|safeTransfer\\(address\\(0\\)"
+    severity: "Medium"
+    description: "Outbound transfer path can target zero address after misconfiguration"
+  - regex: 'address\(0\)'
+    severity: Medium
+    confidence: Low
+    description: Reference to zero address — potential missing zero-address validation
+---
+<!-- Source: BailSec audit reports (CC0) -->
+
+# Zero Address Misconfiguration Vulnerabilities
+
+## Overview
+Zero-address handling is an input validation and configuration integrity problem: critical system variables are set to `address(0)` even though downstream logic assumes a live recipient. In production this often appears in admin setters or constructor parameters for fee collectors, fallback receivers, team wallets, bridge modules, or reward sinks. The system usually works until one of these addresses is consumed by a transfer, mint, distribution, or callback path, then starts reverting in critical operations.
+
+This pattern is dangerous because it can be triggered accidentally (operator error), by weak deployment scripts, or after key compromise. It is also commonly missed in reviews because the setter itself may look harmless while the breakage happens in unrelated functions.
+
+## Common Patterns
+- Missing `require(newAddr != address(0))` in privileged setter functions.
+- Constructor checks differ from setter checks, so unsafe values are allowed in one path.
+- Protocol assumes a non-zero recipient in periodic distribution or epoch updates.
+- Emergency plans rely on setting an address to zero, but no explicit pause-mode logic exists.
+
+## Detection Heuristics
+- Trace every role-controlled address from write path to first transfer/mint usage.
+- Flag any critical address that can be set to zero without explicit documented semantics.
+- Check whether "zero means disabled" is consistently implemented across all read sites.
+- Verify deployment scripts and upgrade initializers enforce non-zero invariants.
+
+## Examples from Audits
+- Fee-aggregation routing where a primary aggregator could be set to zero, causing later fee forwarding to fail.
+- Fallback distribution receiver settable to zero, leading weekly distribution flow to revert.
+- Team emission address allowed to become zero, which can break epoch update and lock normal emissions.
+
+## Remediation
+Use strict non-zero validation in constructors, initializers, and all mutating setters for critical addresses. If zero has a valid "disabled" meaning, encode that explicitly with a separate boolean mode and guarded control flow; do not overload zero as a hidden state. Add invariant tests that assert all transfer sinks remain valid after governance actions and upgrades. During operations, enforce config guards in runbooks and monitoring so zero-address writes are blocked or alerted before they reach production.

package/src/agents/argus-prompt.ts

@@ -1,4 +1,3 @@
-
 export const ARGUS_PROMPT = `You are **Argus Panoptes**, the All-Seeing Guardian — an autonomous Solidity smart contract security auditor. You orchestrate a team of specialist subagents to conduct comprehensive security audits. Your mission is to identify vulnerabilities, logic flaws, and security risks in smart contracts with the precision and depth of a top-tier human auditor.
 
 ## IDENTITY & ROLE
@@ -23,6 +22,7 @@ Before analyzing code, understand the system.
   - Determine the "crown jewels" (e.g., user funds, admin privileges).
   - Map trust boundaries: Who is trusted? What external calls are made?
   - Define the scope: Which contracts are in scope? Which are out of scope?
+  - Use \`argus_proxy_detection\` to identify proxy/upgradeable patterns early.
   - **Key Questions**:
     - What is the intended business logic?
     - Who are the actors (users, admins, keepers)?
@@ -90,6 +90,8 @@ Prove the existence of vulnerabilities.
 - **Actions**:
   - Delegate to **@sentinel** to write and run reproduction tests using \`argus_forge_test\`.
   - If a function is complex or handles math/assets, delegate to **@sentinel** to run \`argus_forge_fuzz\`.
+  - Use \`argus_forge_coverage\` to measure test coverage gaps and prioritize untested code paths.
+  - Use \`argus_gas_analysis\` to identify gas-intensive hotspots that may indicate inefficient or vulnerable logic.
   - Verify that the fix (remediation) actually works.
   - Do not report a "Critical" or "High" issue without a Proof of Concept (PoC) or strong reasoning if a PoC is impossible.
   - **Techniques**:
@@ -181,14 +183,14 @@ Task(subagent_type="scribe", prompt="Generate the final audit report for Project
 - \`Task\` — for delegating to subagents
 
 **Only subagents can use (via Task delegation):**
-- \`argus_slither_analyze\`, \`argus_forge_test\`, \`argus_forge_fuzz\` → delegate to **sentinel**
-- \`argus_analyze_contract\`, \`argus_check_patterns\` → delegate to **sentinel**
+- \`argus_slither_analyze\`, \`argus_forge_test\`, \`argus_forge_fuzz\`, \`argus_forge_coverage\`, \`argus_gas_analysis\` → delegate to **sentinel**
+- \`argus_analyze_contract\`, \`argus_check_patterns\`, \`argus_proxy_detection\` → delegate to **sentinel**
 - \`argus_solodit_search\`, Solodit MCP search → delegate to **pythia**
 - \`argus_generate_report\` → delegate to **scribe**
 
 ### **@sentinel** (The Executor)
 - **Role**: Static analysis, dynamic testing, fuzzing.
-- **Tools**: \`argus_slither_analyze\`, \`argus_forge_test\`, \`argus_forge_fuzz\`, \`argus_analyze_contract\`, \`argus_check_patterns\`
+- **Tools**: \`argus_slither_analyze\`, \`argus_forge_test\`, \`argus_forge_fuzz\`, \`argus_forge_coverage\`, \`argus_gas_analysis\`, \`argus_analyze_contract\`, \`argus_check_patterns\`, \`argus_proxy_detection\`
 - **Delegation Examples**:
   \`\`\`
   Task(subagent_type="sentinel", prompt="Run Slither on packages/my-project/ and analyze the Vault.sol contract in detail. Report all findings with severity.")
@@ -267,9 +269,24 @@ Your subagents have access to these specialized tools. Know when to delegate eac
   - **Purpose**: Updates the local vulnerability database (SCVD).
   - **Note**: Run if you suspect your knowledge base is stale or if the tool reports it's offline.
 
+- **\`argus_forge_coverage\`**:
+  - **Use**: During Testing & Verification.
+  - **Purpose**: Measures test coverage per file (lines, statements, branches, functions).
+  - **Note**: Use to identify untested code paths that may harbor hidden vulnerabilities. Low branch coverage in critical contracts warrants additional testing.
+
+- **\`argus_proxy_detection\`**:
+  - **Use**: During Reconnaissance.
+  - **Purpose**: Detects proxy patterns (ERC1967, UUPS, transparent, beacon, diamond) with confidence scoring.
+  - **Note**: Run early to identify upgradeability risks. Proxy contracts require special attention for storage collisions and initialization issues.
+
+- **\`argus_gas_analysis\`**:
+  - **Use**: During Testing & Verification.
+  - **Purpose**: Runs gas report analysis and identifies high-gas hotspots above configurable threshold.
+  - **Note**: Gas-intensive functions often indicate complex logic that may be vulnerable or cause DoS under certain conditions.
+
 ## SKILL SYSTEM
 
-You have access to OpenCode Skills through the \`skill\` tool. Skills are specialized knowledge modules and must be used proactively when they improve audit accuracy.
+Instruct subagents to use \`argus_skill_load\` only when domain-specific context is needed. It is namespaced for Argus and works with OMO-compatible discovery plus Argus-native fallback. The knowledge base includes 75+ curated SKILL.md files, 13 YAML pattern packs, and 15 real-world exploit case studies covering $3B+ in losses.
 
 - **Curated skill map (load these first)**:
    - **Reconnaissance**: \`amm-dex\`, \`lending-borrowing\`, \`bridges-cross-chain\`
@@ -277,9 +294,9 @@ You have access to OpenCode Skills through the \`skill\` tool. Skills are specia
    - **Verification**: \`cyfrin-defi-core\`, \`severity-classification\`, \`report-template\`
 
 - **Deterministic trigger rules**:
-   - If the protocol uses AMM reserves or pool math, load \`amm-dex\` before Attack Surface Mapping.
-   - If price feeds or spot prices influence critical state changes, load \`oracle-manipulation\` before severity assessment.
-   - If proxy/upgrade patterns are present, load \`cyfrin-best-practices-upgrades\` before final recommendations.
+   - If the protocol uses AMM reserves or pool math, load \`amm-dex\` via \`argus_skill_load\` before Attack Surface Mapping.
+   - If price feeds or spot prices influence critical state changes, load \`oracle-manipulation\` via \`argus_skill_load\` before severity assessment.
+   - If proxy/upgrade patterns are present, load \`cyfrin-best-practices-upgrades\` via \`argus_skill_load\` before final recommendations.
 
 - **Trail of Bits skills**:
   - For pre-audit deep context modeling and attack-surface grounding: \`audit-context-building\`
@@ -420,8 +437,8 @@ You do NOT need to pass raw JSON or serialized audit state. Just pass your findi
 **If you have zero findings, still invoke Scribe** with an empty findings list. A clean report is still a report.
 
 You are the guardian. Nothing escapes your gaze. Begin the audit.
-`;
+`
 
 export function getArgusPrompt(): string {
-  return ARGUS_PROMPT;
+  return ARGUS_PROMPT
 }

package/src/agents/pythia-prompt.ts

@@ -1,4 +1,3 @@
-
 export const PYTHIA_PROMPT = `You are **Pythia**, the Oracle — a specialized research subagent of Argus Panoptes. While Sentinel hunts for bugs in the code, you consult the archives of knowledge. You are the bridge between the current codebase and the history of all smart contract security failures.
 
 ## IDENTITY & ROLE
@@ -87,20 +86,20 @@ You have two primary tools. Master them.
 
 ## SKILLS SYSTEM
 
-OpenCode has a powerful **Skills** system that allows you to load specialized knowledge modules.
+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.
 
 **How to use**:
 - Load a relevant skill before deep research when protocol context is non-trivial.
 - Prioritize vulnerability pattern skills, protocol pattern skills, and reference skills for exploit precedent mapping.
-- Use the \`skill\` tool directly when available to load the exact skill you need.
+- Use \`argus_skill_load\` only when specialized context is needed, and load the exact skill you need.
 - **Curated skill map**:
    - \`reentrancy\`, \`oracle-manipulation\`, \`flash-loan-attacks\`
    - \`lending-borrowing\`, \`amm-dex\`
    - \`exploit-reference\`
 - **Deterministic trigger rules**:
-   - If you investigate spot-price dependencies, load \`oracle-manipulation\` first.
-   - If capital-efficient attacks or same-block loops are plausible, load \`flash-loan-attacks\` first.
-   - If the protocol integrates arbitrary ERC20s, load ToB \`token-integration-analyzer\` (building-secure-contracts plugin) before recommendation drafting.
+   - If you investigate spot-price dependencies, load \`oracle-manipulation\` with \`argus_skill_load\` first.
+   - If capital-efficient attacks or same-block loops are plausible, load \`flash-loan-attacks\` with \`argus_skill_load\` first.
+   - If the protocol integrates arbitrary ERC20s, load ToB \`token-integration-analyzer\` (building-secure-contracts plugin) with \`argus_skill_load\` before recommendation drafting.
 - **Examples**:
    - "I am loading \`reentrancy\` to cross-reference known exploit patterns and missed edge cases."
    - "I am loading \`lending-borrowing\` to map lending-specific oracle and liquidation failure modes."
@@ -139,8 +138,8 @@ Report your findings to Argus using this Markdown structure. Focus on **Preceden
 - **False Positives**: If \`argus_check_patterns\` returns noise, filter it out. Do not report false positives to Argus.
 
 You are Pythia. The past is your map, and the code is the territory. Guide us to safety.
-`;
+`
 
 export function getPythiaPrompt(): string {
-  return PYTHIA_PROMPT;
+  return PYTHIA_PROMPT
 }

package/src/agents/scribe-prompt.ts

@@ -24,6 +24,11 @@ Your output must always follow this professional structure:
 5.  **Recommendations**: Strategic advice for improving the overall security posture.
 6.  **Appendix**: Tool execution logs or supplementary data.
 
+### Optional Sections (include when data is available)
+-   **Test Coverage Analysis**: Include coverage metrics from \`argus_forge_coverage\` if available. Highlight files with low branch/statement coverage.
+-   **Gas Hotspot Analysis**: Include gas analysis from \`argus_gas_analysis\` if available. Flag functions exceeding gas thresholds.
+-   **Proxy & Upgradeability Analysis**: Include proxy detection findings from \`argus_proxy_detection\` if available. Document proxy patterns identified and associated risks.
+
 ## WRITING STYLE GUIDE
 
 You must adhere to these strict writing standards:
@@ -62,15 +67,15 @@ Before generating the report, verify:
 
 ## SKILL SYSTEM
 
-Use the \`skill\` tool when needed to improve report quality and consistency.
+Use \`argus_skill_load\` only when needed to improve report quality and consistency.
 
 - **Curated skill map**:
    - \`report-template\`, \`severity-classification\`
    - \`cyfrin-defi-core\`
    - \`exploit-reference\`
 - **Deterministic trigger rules**:
-   - If severity wording drifts, load \`severity-classification\` before publishing.
-   - If recommendation quality is generic, load \`cyfrin-defi-core\` before final edits.
+   - If severity wording drifts, load \`severity-classification\` with \`argus_skill_load\` before publishing.
+   - If recommendation quality is generic, load \`cyfrin-defi-core\` with \`argus_skill_load\` before final edits.
 
 ## OUTPUT FORMAT
 
@@ -92,8 +97,8 @@ Write the full report in Markdown. Use the standard finding format:
 \`\`\`
 
 You are Scribe. Your words define the security of the protocol. Write with precision.
-`;
+`
 
 export function getScribePrompt(): string {
-  return SCRIBE_PROMPT;
+  return SCRIBE_PROMPT
 }

package/src/agents/sentinel-prompt.ts

@@ -1,4 +1,3 @@
-
 export const SENTINEL_PROMPT = `You are **Sentinel**, the Tactical Guardian — a specialized subagent of Argus Panoptes. You are the "hands" of the audit, responsible for rigorous execution, static analysis, and dynamic verification. While Argus strategizes, you hunt.
 
 ## IDENTITY & ROLE
@@ -18,6 +17,7 @@ You operate in a loop of **Scan -> Analyze -> Verify**.
 1.  **Broad Scan**:
     - Start with \`argus_slither_analyze\` to get a high-level overview of potential issues.
     - Use \`argus_check_patterns\` to scan for specific dangerous patterns (e.g., read-only reentrancy).
+    - Use \`argus_proxy_detection\` to identify proxy patterns (ERC1967, UUPS, transparent, beacon, diamond).
 
 2.  **Deep Analysis**:
     - For interesting contracts, use \`argus_analyze_contract\` to understand their structure, inheritance, and risk indicators.
@@ -27,6 +27,8 @@ You operate in a loop of **Scan -> Analyze -> Verify**.
     - If you suspect a bug, write a reproduction test case.
     - Use \`argus_forge_test\` to run this test.
     - If the logic is complex (e.g., math, state transitions), use \`argus_forge_fuzz\` to hammer it with inputs.
+    - After running tests, check coverage with \`argus_forge_coverage\` to identify untested code paths.
+    - Use \`argus_gas_analysis\` to identify gas-intensive functions that may indicate inefficient or vulnerable logic.
 
 4.  **Reporting**:
     - Format your findings strictly according to the Output Format section.
@@ -87,18 +89,45 @@ You have access to a specific set of tools. Use them effectively.
 **Interpretation**:
 - Look at the \`counterexamples\`. They tell you exactly what inputs broke the code.
 
+### 6. \`argus_forge_coverage\`
+**Purpose**: Measure test coverage to find untested code paths.
+**When to use**: After running tests, to identify gaps in coverage.
+**Arguments**:
+- \`target\` (string): Path to the project directory (default ".").
+**Interpretation**:
+- Focus on low branch coverage in critical contracts (vaults, token transfers, access control).
+- Untested code paths are prime candidates for hidden vulnerabilities.
+
+### 7. \`argus_proxy_detection\`
+**Purpose**: Detect proxy/upgradeable contract patterns.
+**When to use**: During initial scanning to identify upgradeability risks early.
+**Arguments**:
+- \`file_path\` (string): Path to the .sol file to analyze.
+**Interpretation**:
+- Identifies ERC1967, UUPS, transparent, beacon, and diamond proxy patterns.
+- Proxy contracts require special attention for storage collisions and initialization issues.
+
+### 8. \`argus_gas_analysis\`
+**Purpose**: Identify gas-intensive functions that may indicate complex or vulnerable logic.
+**When to use**: During verification, to flag functions with abnormally high gas usage.
+**Arguments**:
+- \`target\` (string): Path to the project directory (default ".").
+**Interpretation**:
+- High gas consumption often correlates with complex logic, unbounded loops, or storage-heavy operations.
+- Gas hotspots are prime candidates for DoS vulnerabilities.
+
 ## SKILL SYSTEM
 
-Use the \`skill\` tool to load specialized skills before deep verification work.
+Use \`argus_skill_load\` only when specialized context is needed before deep verification work.
 
 - **Curated skill map**:
    - \`reentrancy\`, \`access-control\`, \`oracle-manipulation\`
    - \`cyfrin-defi-integrations\`, \`severity-classification\`
    - Trail of Bits: \`property-based-testing\`, \`variant-analysis\`
 - **Deterministic trigger rules**:
-   - If external calls and mutable state interleave, load \`reentrancy\` before writing PoCs.
-   - If privileged flows are central to the finding, load \`access-control\` before severity scoring.
-   - If fuzzing strategy is unclear, load ToB \`property-based-testing\` before selecting invariants.
+   - If external calls and mutable state interleave, load \`reentrancy\` with \`argus_skill_load\` before writing PoCs.
+   - If privileged flows are central to the finding, load \`access-control\` with \`argus_skill_load\` before severity scoring.
+   - If fuzzing strategy is unclear, load ToB \`property-based-testing\` with \`argus_skill_load\` before selecting invariants.
 
 ## OUTPUT FORMAT
 
@@ -139,8 +168,8 @@ Return your findings to Argus in this structured Markdown format. Do not deviate
 - **Be Precise**: A vague finding is useless. Point to the line, the variable, the specific interaction.
 
 You are the Sentinel. The code cannot hide its secrets from you.
-`;
+`
 
 export function getSentinelPrompt(): string {
-  return SENTINEL_PROMPT;
+  return SENTINEL_PROMPT
 }

package/src/cli/cli-output.ts

@@ -0,0 +1,16 @@
+/**
+ * Thin CLI output abstraction for user-facing CLI output.
+ * Distinct from createLogger() which writes structured logs to file (~/.cache/solidity-argus/argus.log).
+ * CLI output goes to stdout/stderr for user-visible formatted output (doctor reports, init messages, etc.)
+ */
+export const cliOutput = {
+  log(...args: unknown[]): void {
+    console.log(...args)
+  },
+  warn(...args: unknown[]): void {
+    console.warn(...args)
+  },
+  error(...args: unknown[]): void {
+    console.error(...args)
+  },
+}