Give it to your agent.

The gate

Your agent compares the version you trust against the incoming one before it installs.

vigi diff --old <trusted> --new <incoming> --json

• Exit code 0: nothing gained a power. The agent proceeds.
• Exit code 1: a file gained a power. The agent stops and reads the findings.
• The JSON record is the only thing written to stdout, so it stays clean to parse.

What it hands back

One record per comparison. Each finding shows the file and the power it gained.

{
  "format": "vigi-diff",
  "format_version": 1,
  "target": "left-pad-1.4.0",
  "files_now": 3,
  "files_before": 3,
  "verdict": "HEADS UP",
  "exit_code": 1,
  "findings": [
    {
      "path": "index.js",
      "new": false,
      "loudness": "high",
      "size": 512,
      "powers_gained": ["can run other programs", "can reach the network"],
      "powers_gained_raw": ["exec", "fetch"],
      "talks_to": ["evil.example"]
    }
  ]
}

verdict is OK or HEADS UP. loudness is high, medium, or low. Read powers_gained_raw in code, powers_gained for a person.

As a hook

One command brackets an npm install with a snapshot before and a check after.

vigi hook npm

Or gate it yourself in a harness, and act on the exit code.

vigi diff --old ./prev --new ./incoming --json > vigi.json || echo "review vigi.json before trusting this update"

In your agent's instructions

Drop one rule into AGENTS.md or CLAUDE.md. The agent runs the gate on its own.

Before you install or upgrade any dependency, run:

  vigi diff --old <current version> --new <incoming version> --json

If the exit code is 1, do not proceed. Show the findings and let a person decide.

The one limit

Vigilance compares two versions, so it needs a version you already trust. On a brand-new package there is nothing to diff, so run the gate on updates. For a first install, vigi profile --artifact <path> still lists the powers a file holds.