How to Check a Coding Agent's Package Installs with the Claude Code Hook

Beginner 5 minutes Developers / Security Engineers AI Assistant Updated

Run the Chainsaw install guard on every package install Claude Code is about to run — npm, pip, npx, uvx and the rest — and turn a malicious or typosquatted package into a refusal the agent reads, before anything is fetched.

What This Gets You

A coding agent installs whatever it decides it needs, including a package name it misremembered or invented, without anyone reading the command first. The Chainsaw Claude Code plugin checks every install in a Bash command before Bash runs it. When the install guard would refuse a package, Claude Code gets a deny with the reason, nothing is fetched, and the agent is told to check the name and ask you rather than retry another way.

It runs the same checks as the install guard (known-malicious packages, typosquats, offline by default), and it covers spellings the shell guard cannot see:

Command the agent runsShell guardAgent hook
npm install x, pip install x, yarn add x, uv add x …checked when the agent’s shell loads your rc filechecked
command npm i x, /opt/homebrew/bin/npm i x, python3 -m pip install xnot checkedchecked
npx x, npm exec x, npm create x, pnpm dlx x, yarn create x, bunx xnot checkedchecked
uvx x, uv tool run x, pipx run xnot checkedchecked
bash -c "npm i x", cd web && npm ci (reads web/’s lockfile)partlychecked

You don’t need a Chainsaw account: the checks run on your machine. If you are signed in, the same server lookup the shell guard makes for npm and Homebrew installs runs here too.

Prerequisites

  • Claude Code.
  • The chainsaw CLI on your PATH, recent enough to have chainsaw guard agent-hook. Check with:
chainsaw guard agent-hook --help

If that prints the general chainsaw guard help instead of a page about the agent hook, update the CLI (Step 1).

Step 1: Install or Update the CLI

curl -fsSL https://chain305.com/install.sh | sh

The same command updates an existing install. For Windows and what the installer changes, see How to Block Malicious Packages at Install Time.

Step 2: Install the Plugin

claude plugin marketplace add Chain305/chainsaw-core
claude plugin install chainsaw-guard@chainsaw

Then run /reload-plugins in an open Claude Code session, or start a new one.

At session start the plugin checks the CLI. If chainsaw is missing or too old, you see a chainsaw-guard: warning saying installs are not being checked, with the command to fix it. No warning means the hook is active.

Step 3: Check It Works, Without Installing Anything

Hand the hook the payload Claude Code would send for an install of a known-malicious package. This runs the check only; nothing is installed:

printf '{"tool_name":"Bash","tool_input":{"command":"npm install lodahs"}}' | chainsaw guard agent-hook

You should get one line of JSON with "permissionDecision":"deny". Claude Code shows the agent this reason:

Chainsaw refused this install; nothing was run.
- npm:lodahs: known-malicious (MAL-2025-25502) — the advisory covers every version of lodahs; …
Do not retry it another way (another package manager, a direct path, npx, or a script).
Check that the package name is the one intended. If this exact package is needed,
stop and ask the user to review it.

A command with no refused install prints nothing and runs as normal:

printf '{"tool_name":"Bash","tool_input":{"command":"npm install lodash"}}' | chainsaw guard agent-hook

What the Agent Sees

  • A refused install: a deny with the reason. The command does not run.
  • A package name only known at run time (npm i "$PKG", xargs npm install): Claude Code asks you to approve the command, because the name cannot be checked until it runs.
  • Everything else: nothing. The hook never approves a command on your behalf, so your own permission settings still decide.

If a package is refused and you have checked it is the one you want, run the install yourself in your terminal. The shell guard shows the chainsaw guard allow command for a typosquat verdict there. The agent is deliberately not shown it.

Settings It Shares with the Shell Guard

  • CHAINSAW_GUARD_SKIP=npm (comma-separated) turns the check off for those managers. Set it in the environment Claude Code starts from.
  • CHAINSAW_COVERAGE_MODE=closed refuses installs when a required signal source is missing, exactly as it does for the shell guard. Without it, a missing source never blocks.
  • Signed out, every check runs on your machine. Signed in, npm and Homebrew installs also get the server lookup, as they do in the shell guard. CHAINSAW_OFFLINE=1 turns that lookup off.

Set It Up Without the Plugin

Add this to ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "chainsaw guard agent-hook; s=$?; [ \"$s\" -eq 2 ] && exit 1; exit \"$s\""
          }
        ]
      }
    ]
  }
}

Keep the exit-status part of the command: Claude Code treats exit status 2 as “block this command”, so it is turned into 1, an error Claude Code shows without blocking. The plugin does the same, and also adds the session-start check.

Limits

  • It reads command text. An install inside a script file, a Makefile or node -e is not checked. It is a second check beside the shell guard, not enforcement. For installs nobody can route around, point package managers at the Chainsaw proxy.
  • Not covered yet: bun add / bun install.
  • MCP servers your agent app launches with npx -y … are started by the app, not through Bash, so the hook never sees them. The proxy does, through your .npmrc.

Troubleshooting

SymptomCauseFix
chainsaw-guard: the chainsaw CLI is not on PATH at session startClaude Code’s environment has no chainsawRun Step 1, then restart Claude Code
chainsaw-guard: this chainsaw CLI predates the agent hookAn older CLIRun Step 1 to update
A hook error after every Bash commandThe hook was added by hand with a typo, or an unsupported --formatCompare with the snippet above
An install the guard refused still ranIt was in a script file, or CHAINSAW_GUARD_SKIP names that managerSee Limits; check the environment