@vaclavbelak/pi-sage

Sage (Safety for Agents) connector for the pi coding agent

Packages

Package details

extension

Install @vaclavbelak/pi-sage from npm and Pi will load the resources declared by the package manifest.

npm home report

$ pi install npm:@vaclavbelak/pi-sage

Package: @vaclavbelak/pi-sage
Version: 0.3.1
Published: Oct 21, 2026
Downloads: 646/mo · 6/wk
Author: vaclavbelak
License: Apache-2.0
Types: extension
Size: 276.1 KB
Dependencies: 2 dependencies · 1 peer

Pi manifest JSON

{
  "extensions": [
    "./extensions/sage.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-sage

Sage (Safety for Agents) for the pi coding agent. Checks tool calls against Sage's threat detection before they run.

Install

pi install npm:@vaclavbelak/pi-sage

Pi installs the dependencies (@gendigital/sage-core, @gendigital/sage-mcp) from npm.

From a local checkout:

npm install && npm run sync:assets   # local installs are not managed by pi
pi install /path/to/pi-sage

Installing from git is not supported: the bundled threat rules in resources/ are generated, not committed.

Publishing: npm publish (the prepack step runs sync:assets, which needs the Sage repo at ../sage or SAGE_REPO=/path/to/sage).

What it does

pi event	Sage hook	Behaviour
`tool_call`	PreToolUse	`deny` blocks the call. `ask` opens a confirmation dialog; without a UI (print/JSON/RPC mode) it is denied.
`tool_result`	PostToolUse	Appends a note after an approved action, medium-risk prompt-injection warnings, and heuristic scan results for tool output.
`session_start`	SessionStart	Scans installed pi extensions/packages and skills; shows notices and findings.

With manage_status_line enabled in ~/.sage/config.json (default), the extension maintains a footer status line (blocked/flagged counts and recent reason, plus fresh risky skill findings) via pi's status API. Disable it there if you set your own.

Covered tools: bash, powershell, read, write, edit, grep, find, ls, plus web_search, fetch_content and source_check from pi-web-access (get_search_content is a local lookup and is not mapped).

The Sage MCP server is registered as sage, providing sage_report_false_positive and sage_list_audit_entries. It requires pi's built-in MCP support (on by default).

Errors inside Sage never block a tool (fail-open). Configuration, allowlists and exceptions are the standard Sage ones in ~/.sage/; see the Sage user guide.

Development

npm install
npm run sync:assets   # needs the Sage repo at ../sage (or SAGE_REPO=...)
npm test
PI_SAGE_E2E=1 npm run test:e2e   # live pi run with Sage's canary rules

License

Apache-2.0. Threat definitions bundled from the Sage repository are under their own Detection Rule License.