@architectit/pi-guardrails

Four Laws guardrails enforcement for the pi coding agent. Works standalone (no MCP server required) and can bridge to the existing Go MCP server when available.

Installation

pi install npm:@architectit/pi-guardrails

Or manually:

npx @architectit/pi-guardrails

Architecture

Hybrid design: The extension operates in two modes:

• Standalone (default): All enforcement runs locally within the pi extension. No external server needed.
• MCP Bridge: When the Go MCP server is available, tools proxy to it for enhanced enforcement.

The standalone mode is the primary value proposition — teams don't need to run the MCP server to get guardrails protection.

The Four Laws of Agent Safety

1. Read Before Editing — The agent must read a file before editing it
2. Stay in Scope — The agent only operates on authorized file paths
3. Verify Before Committing — Changes must be verified before committing
4. Halt When Uncertain — The Three Strikes rule: 3 consecutive failures triggers a halt

Tools (28 registered)

Core Enforcement

| Tool | Purpose | |------|---------| | guardrail_init | Initialize a guardrails session | | guardrail_record_read | Mark a file as read (Law 1) | | guardrail_verify_read | Check if a file was read before editing | | guardrail_set_scope | Define authorized file paths (Law 2) | | guardrail_check_scope | Check if a path is in scope | | guardrail_record_attempt | Record a task attempt result (Law 4) | | guardrail_check_strikes | Check strike count for a task | | guardrail_reset_strikes | Reset strikes after resolution | | guardrail_check_halt | Evaluate halt conditions (includes uncertainty score) | | guardrail_log_violation | Log a guardrail violation | | guardrail_status | Get current session status | | guardrail_acknowledge_halt | Acknowledge a halt condition to resume |

Language & Pattern Rules

| Tool | Purpose | |------|---------| | guardrail_detect_language | Auto-detect project languages | | guardrail_get_language_profile | Get language profile with available rules | | guardrail_check_pattern | Check code against prevention pattern rules | | guardrail_list_languages | List available language rule sets | | guardrail_list_skills | List all guardrails skills | | guardrail_read_skill | Read a skill's documentation |

Regression & Validation

| Tool | Purpose | |------|---------| | guardrail_check_regression | Check if file edits risk regressing past failures | | guardrail_verify_fixes | Verify that past fixes are still intact | | guardrail_register_failure | Register a failure in the cross-session registry | | guardrail_validate_replacement | Validate edit old_content matches actual file | | guardrail_validate_git | Validate git operations (branch protection, force-push) |

Planning & Scope

| Tool | Purpose | |------|---------| | guardrail_pre_work_check | Generate pre-work risk checklist | | guardrail_detect_creep | Detect feature creep against authorized scope | | guardrail_mcp | Proxy to MCP server (when connected) |

Automatic Enforcement

The extension registers event handlers that enforce the Four Laws automatically:

• Read tracking: File reads are tracked via tool_result events
• Pre-edit enforcement: Edits to unread files are blocked (Law 1)
• Scope enforcement: Edits outside the authorized scope are blocked (Law 2)
• Bash safety: Dangerous commands (rm -rf /, git push --force, sudo, etc.) are blocked
• Injection defense: Scans tool inputs for prompt injection patterns
• Output validation: Detects secrets and PII in tool output
• Content filtering: Detects denied topics in output (warn-only)
• Canary tokens: Detects data exfiltration via embedded tokens (warn-only)
• Permission system: Per-tool permission levels (auto/ask/blocked)
• Halt lifecycle: Blocked operations record halt state; requires acknowledgment to resume

Language-Specific Rules

Auto-detects project languages and loads prevention rules from .guardrails/prevention-rules/languages/:

| Language | Rules | Examples | |----------|-------|---------| | Python | 8 | eval/exec, subprocess shell=True, bare except, pickle, SQL injection | | TypeScript | 7 | any type, non-null assertion, eval, innerHTML, hardcoded secrets | | Go | 6 | ignored errors, panic, SQL concat, goroutine without context | | Rust | 6 | unsafe blocks, unwrap, panic!, todo!, raw pointer deref |

Add new languages by creating a JSON file in .guardrails/prevention-rules/languages/.

Configuration

Config file: ~/.pi/agent/extensions/pi-guardrails/config.json

{
  "mcpBinaryPath": "",
  "enabledRules": ["four-laws", "three-strikes", "scope-validator"],
  "autoRegister": true,
  "defaultScope": [],
  "maxStrikes": 3,
  "statusBarEnabled": true,
  "panelAutoOpen": false,
  "toolPermissions": {
    "defaultLevel": "auto",
    "tools": {
      "bash": "ask",
      "write": "auto",
      "edit": "auto",
      "read": "auto"
    }
  },
  "injectionDefense": {
    "blockThreshold": 0.8,
    "warnThreshold": 0.5,
    "heuristicEnabled": true
  },
  "outputValidation": {
    "enablePII": false,
    "autoRedact": false,
    "redactionText": "[REDACTED]",
    "contentFilter": {
      "deniedTopics": ["malicious code"],
      "allowedTopics": [],
      "strictMode": false
    }
  },
  "canary": {
    "prefix": "CATALOG:",
    "tokenLength": 32
  },
  "gitPolicy": {
    "protectedBranches": ["main", "master"],
    "commitFormat": "conventional",
    "requireAIAttribution": true
  }
}

Environment variables:

• PI_GUARDRAILS_MCP_API_KEY — API key for the MCP server

Halt Lifecycle

When a handler blocks an operation, a halt is recorded:

1. active → operation attempted
2. halted → handler blocked, reason recorded
3. acknowledged → guardrail_acknowledge_halt called after review

Uncertainty Scoring

guardrail_check_halt returns an uncertaintyScore (0-1):

| Score | Level | Meaning | |-------|-------|---------| | 0-0.2 | Certain | No concerns | | 0.2-0.5 | Probably | Mild uncertainty (e.g. edit without details) | | 0.5-0.8 | Uncertain | Significant concern (e.g. delete without details) | | 0.8-1.0 | Guessing | High risk (e.g. production-affected operations) |

Status Bar

When enabled, shows a compact status in the pi status bar:

• g: ok — no issues
• g: !!2/3 src/ mcp:* — 2/3 strikes, scope set to src/, MCP connected
• g: src/ !3v mcp:. — scope set, 3 violations, MCP disconnected

TUI Dashboard

Open the guardrails overlay with:

/guardrails

The panel shows safety score, Four Laws status, strike tracker, scope, and MCP connection status.

Close with Esc or q. Scroll with j/k.

MCP Bridge

When the Go MCP server is available, the extension can proxy calls to it for enhanced enforcement:

1. Configure the server endpoint in config.json under mcpBinaryPath (URL for SSE, command for stdio)
2. Initialize a session with guardrail_init — the extension auto-connects
3. Use guardrail_mcp with an action parameter to call any MCP server tool
4. Reconnection uses exponential backoff (1s base, 30s max, 5 attempts)

Storage

All state is stored under ~/.pi/agent/extensions/pi-guardrails/:

• sessions/ — session state JSON files
• violations.jsonl — append-only violation log
• .guardrails/regression/failure-registry.jsonl — cross-session failure registry
• config.json — user configuration

22 Code Modules

FileReadStore, ScopeValidator, StrikeCounter, HaltChecker, ViolationLog, SessionStore, InjectionDetector, OutputValidator, ContentFilter, CanaryTokenManager, PermissionManager, PolicyLoader, MCPClient, PreWorkChecker, FeatureCreepDetector, PatternRuleEngine, GitValidator, LanguageDetector, RegressionGuard, ExactReplacementValidator, SandboxRunner, GuardrailsPanel

CI/CD Integration

Pre-commit Hook

cp guardrails/pre-commit.sh .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

GitHub Actions

The .github/workflows/pi-guardrails-ci.yml workflow runs on PRs:

• Unit tests for pi-extension and guardrails modules
• Secret scanning on changed files
• Scope compliance validation