Controlling Global Dependencies: Windsurf and npm install -g

Correction note (2026-10-13). An earlier version of this article named an Audit tab in the dashboard. The dashboard page is named Audit, and ssg dashboard open opens the dashboard in the browser. ssg audit search queries the local audit log from the command line. Sample output in this article is illustrative, not a recorded run. The local audit log records decisions on a best-effort basis: entries can be dropped if the daemon queue is full, and old rows are deleted at the row caps. It is local, not append-only, and not immutable. ssg eval reads the tool call as JSON on stdin and has no --content, --content-file, --file or positional form. ssg daemon has no --env flag; edit the project rule files or add a waiver with ssg exceptions add.

Describe the task

Windsurf is setting up your project and notices a missing CLI tool. Rather than adding it as a dev dependency, the agent installs it globally for convenience:

npm install -g some-cli-tool@latest

Global installs mutate your system's Node environment, add packages to the shared PATH, and persist across every project. They're also a supply-chain vector — @latest resolves to whatever version the registry serves, which may have changed since you last reviewed it. SSG's ask-npm-global rule routes the install to a human approver.

# illustrative sample output
[ASK] bash › npm install -g some-cli-tool@latest — rule: ask-npm-global
Pending approval in dashboard...

Give SSG context

SSG evaluates Windsurf's shell commands via the SSG MCP Server integration inside Windsurf (Cascade).

Required context

rule ask-npm-global {
  enabled true
  priority 70
  severity warning
  ASK execution
  IF command STARTS_WITH "npm install -g"
  OR command STARTS_WITH "npm i -g"
  PROMPT "Global npm install requires human approval. Review the package before confirming."
  MESSAGE "Global npm install requires human approval. Review the package before confirming."
}

Optional context

For stricter environments, block outright and require dev dependencies instead:

rule deny-npm-global {
  enabled true
  priority 70
  severity error
  DENY execution
  IF command CONTAINS "npm install" AND command CONTAINS " -g"
  MESSAGE "Global installs are not allowed. Add the package as a devDependency instead."
}

What SSG does

On an ASK decision, SSG pauses the tool call and surfaces a pending approval in your ssg dashboard. You see the exact package and version Windsurf is trying to install. Approve to proceed, deny to block with a message the agent can act on.

Redirect the agent to a local dev dependency

Global install was blocked. Add the package as a devDependency instead:
  npm install --save-dev some-cli-tool
Then run it with: npx some-cli-tool

This keeps the dependency scoped to the project and pinned to a reviewable version.

Pin versions to prevent supply-chain drift

Pair with a rule that blocks @latest in package installs:

rule no-latest-tag {
  enabled true
  priority 65
  severity warning
  ASK execution
  IF command CONTAINS "npm install"
  AND command CONTAINS "@latest"
  PROMPT "@latest resolves at runtime. Specify a pinned version instead."
  MESSAGE "@latest resolves at runtime. Specify a pinned version instead."
}

Audit all package installs

npm installs (global or local) are logged on a best-effort basis with the package name, version, and whether it was approved, denied, or blocked. Run ssg dashboard open and use the Audit page to review what Windsurf installed across all sessions.

How your rule handles command variations

Agents use npm install -g, npm i -g, and sometimes npm add -g. List all variants in your rule or use a broader CONTAINS " -g" condition. Test with echo '{"tool":"Bash","input":{"command":"npm install -g typescript"}}' | ssg eval.

Check the rule against your container setup

If you use a Docker-based dev environment where global installs are isolated to the container, you may want to allow them. Allow them for that project by editing the rule in its .sigmashake/rules files, or record a waiver with ssg exceptions add <rule-id> --reason <reason-code> --justification <text>.