{"_id":"@architectit/pi-guardrails","_rev":"2-9cd993df0a3a881129307e2abb0bf8b8","name":"@architectit/pi-guardrails","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@architectit/pi-guardrails","version":"0.1.0","keywords":["pi-package","pi","pi-coding-agent","guardrails","safety","ai-agents"],"author":{"name":"TheArchitectit"},"license":"MIT","_id":"@architectit/pi-guardrails@0.1.0","maintainers":[{"name":"architectit","email":"roger@vroger.com"}],"homepage":"https://github.com/TheArchitectit/agent-guardrails-template#readme","bugs":{"url":"https://github.com/TheArchitectit/agent-guardrails-template/issues"},"pi":{"skills":["./skills"],"extensions":["./index.ts"]},"bin":{"pi-guardrails":"install.mjs"},"dist":{"shasum":"4a3f8b438e466d492370d40abd7844b682e4a236","tarball":"https://registry.npmjs.org/@architectit/pi-guardrails/-/pi-guardrails-0.1.0.tgz","fileCount":38,"integrity":"sha512-vmM5TVlpfNSllaH3qRMYeovPX/gP3CYO+yv451A+sJq0GX/NTsPkjenURRWsjczPu4zONnSfmFwRR6RdV2TRUA==","signatures":[{"sig":"MEQCICgJQCvp9/YLtlvC0OPxPMl4MhmyUUD/wM9tod0y4y69AiA3dT9to/KMrGcVEYn1MyEFGUeSH0l1KY4VAgo5f/kqVA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":125178},"type":"module","gitHead":"12b2664a4535c650eafb870a4805558083d60790","scripts":{"test":"vitest run","test:watch":"vitest"},"_npmUser":{"name":"architectit","email":"roger@vroger.com"},"repository":{"url":"git+https://github.com/TheArchitectit/agent-guardrails-template.git","type":"git","directory":"pi-extension"},"_npmVersion":"11.14.1","description":"Four Laws guardrails enforcement for pi coding agent — standalone + MCP bridge","directories":{},"_nodeVersion":"26.1.0","dependencies":{"@sinclair/typebox":"^0.34.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.1.8"},"peerDependencies":{"@earendil-works/pi-tui":"*","@earendil-works/pi-coding-agent":"*"},"peerDependenciesMeta":{"@earendil-works/pi-tui":{"optional":true},"@earendil-works/pi-coding-agent":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/pi-guardrails_0.1.0_1778998680339_0.07860841025324872","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@architectit/pi-guardrails","version":"0.2.0","description":"Four Laws guardrails enforcement for pi coding agent — standalone + MCP bridge","type":"module","author":{"name":"TheArchitectit"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/TheArchitectit/agent-guardrails-template.git","directory":"pi-extension"},"keywords":["pi-package","pi","pi-coding-agent","guardrails","safety","ai-agents"],"bin":{"pi-guardrails":"install.mjs"},"pi":{"extensions":["./index.ts"],"skills":["./skills"]},"dependencies":{"@sinclair/typebox":"^0.34.0"},"peerDependencies":{"@earendil-works/pi-coding-agent":"*","@earendil-works/pi-tui":"*"},"peerDependenciesMeta":{"@earendil-works/pi-coding-agent":{"optional":true},"@earendil-works/pi-tui":{"optional":true}},"devDependencies":{"typescript":"^6.0.3","vitest":"^2.1.8"},"scripts":{"test":"vitest run","test:watch":"vitest"},"gitHead":"10242481bb95d6c26bbef9610fd200a705ca625a","_id":"@architectit/pi-guardrails@0.2.0","bugs":{"url":"https://github.com/TheArchitectit/agent-guardrails-template/issues"},"homepage":"https://github.com/TheArchitectit/agent-guardrails-template#readme","_nodeVersion":"26.1.0","_npmVersion":"11.14.1","dist":{"integrity":"sha512-FoWq2PkUy/qysmSEnhTp18gKNlYbpnWynGWFQ9TJhZyL/RPDMX9OMnJFuKBrQqxwUvyQRwsjmJkzxX7k8RPfqA==","shasum":"02fb538987c9a19261ab322777b1c19d25b55b0e","tarball":"https://registry.npmjs.org/@architectit/pi-guardrails/-/pi-guardrails-0.2.0.tgz","fileCount":61,"unpackedSize":230593,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCj4twJIbUViZAmlL6+TC3LSmyNyIwdT/+sx+0mzsO4PQIgbxFGkXF9BEjWYRVfzcMGF6Ed9KaM01SJwlLdI5eIkY4="}]},"_npmUser":{"name":"architectit","email":"roger@vroger.com"},"directories":{},"maintainers":[{"name":"architectit","email":"roger@vroger.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-guardrails_0.2.0_1779278216386_0.9916528968032443"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-17T06:18:00.220Z","modified":"2026-05-20T11:56:56.687Z","0.1.0":"2026-05-17T06:18:00.501Z","0.2.0":"2026-05-20T11:56:56.533Z"},"bugs":{"url":"https://github.com/TheArchitectit/agent-guardrails-template/issues"},"author":{"name":"TheArchitectit"},"license":"MIT","homepage":"https://github.com/TheArchitectit/agent-guardrails-template#readme","keywords":["pi-package","pi","pi-coding-agent","guardrails","safety","ai-agents"],"repository":{"type":"git","url":"git+https://github.com/TheArchitectit/agent-guardrails-template.git","directory":"pi-extension"},"description":"Four Laws guardrails enforcement for pi coding agent — standalone + MCP bridge","maintainers":[{"name":"architectit","email":"roger@vroger.com"}],"readme":"# @architectit/pi-guardrails\n\nFour 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.\n\n## Installation\n\n```bash\npi install npm:@architectit/pi-guardrails\n```\n\nOr manually:\n\n```bash\nnpx @architectit/pi-guardrails\n```\n\n## Architecture\n\n**Hybrid design:** The extension operates in two modes:\n\n- **Standalone** (default): All enforcement runs locally within the pi extension. No external server needed.\n- **MCP Bridge**: When the Go MCP server is available, tools proxy to it for enhanced enforcement.\n\nThe standalone mode is the primary value proposition — teams don't need to run the MCP server to get guardrails protection.\n\n## The Four Laws of Agent Safety\n\n1. **Read Before Editing** — The agent must read a file before editing it\n2. **Stay in Scope** — The agent only operates on authorized file paths\n3. **Verify Before Committing** — Changes must be verified before committing\n4. **Halt When Uncertain** — The Three Strikes rule: 3 consecutive failures triggers a halt\n\n## Tools (28 registered)\n\n### Core Enforcement\n\n| Tool | Purpose |\n|------|---------|\n| `guardrail_init` | Initialize a guardrails session |\n| `guardrail_record_read` | Mark a file as read (Law 1) |\n| `guardrail_verify_read` | Check if a file was read before editing |\n| `guardrail_set_scope` | Define authorized file paths (Law 2) |\n| `guardrail_check_scope` | Check if a path is in scope |\n| `guardrail_record_attempt` | Record a task attempt result (Law 4) |\n| `guardrail_check_strikes` | Check strike count for a task |\n| `guardrail_reset_strikes` | Reset strikes after resolution |\n| `guardrail_check_halt` | Evaluate halt conditions (includes uncertainty score) |\n| `guardrail_log_violation` | Log a guardrail violation |\n| `guardrail_status` | Get current session status |\n| `guardrail_acknowledge_halt` | Acknowledge a halt condition to resume |\n\n### Language & Pattern Rules\n\n| Tool | Purpose |\n|------|---------|\n| `guardrail_detect_language` | Auto-detect project languages |\n| `guardrail_get_language_profile` | Get language profile with available rules |\n| `guardrail_check_pattern` | Check code against prevention pattern rules |\n| `guardrail_list_languages` | List available language rule sets |\n| `guardrail_list_skills` | List all guardrails skills |\n| `guardrail_read_skill` | Read a skill's documentation |\n\n### Regression & Validation\n\n| Tool | Purpose |\n|------|---------|\n| `guardrail_check_regression` | Check if file edits risk regressing past failures |\n| `guardrail_verify_fixes` | Verify that past fixes are still intact |\n| `guardrail_register_failure` | Register a failure in the cross-session registry |\n| `guardrail_validate_replacement` | Validate edit old_content matches actual file |\n| `guardrail_validate_git` | Validate git operations (branch protection, force-push) |\n\n### Planning & Scope\n\n| Tool | Purpose |\n|------|---------|\n| `guardrail_pre_work_check` | Generate pre-work risk checklist |\n| `guardrail_detect_creep` | Detect feature creep against authorized scope |\n| `guardrail_mcp` | Proxy to MCP server (when connected) |\n\n## Automatic Enforcement\n\nThe extension registers event handlers that enforce the Four Laws automatically:\n\n- **Read tracking**: File reads are tracked via `tool_result` events\n- **Pre-edit enforcement**: Edits to unread files are blocked (Law 1)\n- **Scope enforcement**: Edits outside the authorized scope are blocked (Law 2)\n- **Bash safety**: Dangerous commands (`rm -rf /`, `git push --force`, `sudo`, etc.) are blocked\n- **Injection defense**: Scans tool inputs for prompt injection patterns\n- **Output validation**: Detects secrets and PII in tool output\n- **Content filtering**: Detects denied topics in output (warn-only)\n- **Canary tokens**: Detects data exfiltration via embedded tokens (warn-only)\n- **Permission system**: Per-tool permission levels (auto/ask/blocked)\n- **Halt lifecycle**: Blocked operations record halt state; requires acknowledgment to resume\n\n## Language-Specific Rules\n\nAuto-detects project languages and loads prevention rules from `.guardrails/prevention-rules/languages/`:\n\n| Language | Rules | Examples |\n|----------|-------|---------|\n| Python | 8 | eval/exec, subprocess shell=True, bare except, pickle, SQL injection |\n| TypeScript | 7 | any type, non-null assertion, eval, innerHTML, hardcoded secrets |\n| Go | 6 | ignored errors, panic, SQL concat, goroutine without context |\n| Rust | 6 | unsafe blocks, unwrap, panic!, todo!, raw pointer deref |\n\nAdd new languages by creating a JSON file in `.guardrails/prevention-rules/languages/`.\n\n## Configuration\n\nConfig file: `~/.pi/agent/extensions/pi-guardrails/config.json`\n\n```json\n{\n  \"mcpBinaryPath\": \"\",\n  \"enabledRules\": [\"four-laws\", \"three-strikes\", \"scope-validator\"],\n  \"autoRegister\": true,\n  \"defaultScope\": [],\n  \"maxStrikes\": 3,\n  \"statusBarEnabled\": true,\n  \"panelAutoOpen\": false,\n  \"toolPermissions\": {\n    \"defaultLevel\": \"auto\",\n    \"tools\": {\n      \"bash\": \"ask\",\n      \"write\": \"auto\",\n      \"edit\": \"auto\",\n      \"read\": \"auto\"\n    }\n  },\n  \"injectionDefense\": {\n    \"blockThreshold\": 0.8,\n    \"warnThreshold\": 0.5,\n    \"heuristicEnabled\": true\n  },\n  \"outputValidation\": {\n    \"enablePII\": false,\n    \"autoRedact\": false,\n    \"redactionText\": \"[REDACTED]\",\n    \"contentFilter\": {\n      \"deniedTopics\": [\"malicious code\"],\n      \"allowedTopics\": [],\n      \"strictMode\": false\n    }\n  },\n  \"canary\": {\n    \"prefix\": \"CATALOG:\",\n    \"tokenLength\": 32\n  },\n  \"gitPolicy\": {\n    \"protectedBranches\": [\"main\", \"master\"],\n    \"commitFormat\": \"conventional\",\n    \"requireAIAttribution\": true\n  }\n}\n```\n\nEnvironment variables:\n- `PI_GUARDRAILS_MCP_API_KEY` — API key for the MCP server\n\n## Halt Lifecycle\n\nWhen a handler blocks an operation, a halt is recorded:\n\n1. **active** → operation attempted\n2. **halted** → handler blocked, reason recorded\n3. **acknowledged** → `guardrail_acknowledge_halt` called after review\n\n## Uncertainty Scoring\n\n`guardrail_check_halt` returns an `uncertaintyScore` (0-1):\n\n| Score | Level | Meaning |\n|-------|-------|---------|\n| 0-0.2 | Certain | No concerns |\n| 0.2-0.5 | Probably | Mild uncertainty (e.g. edit without details) |\n| 0.5-0.8 | Uncertain | Significant concern (e.g. delete without details) |\n| 0.8-1.0 | Guessing | High risk (e.g. production-affected operations) |\n\n## Status Bar\n\nWhen enabled, shows a compact status in the pi status bar:\n\n- `g: ok` — no issues\n- `g: !!2/3 src/ mcp:*` — 2/3 strikes, scope set to `src/`, MCP connected\n- `g: src/ !3v mcp:.` — scope set, 3 violations, MCP disconnected\n\n## TUI Dashboard\n\nOpen the guardrails overlay with:\n\n```\n/guardrails\n```\n\nThe panel shows safety score, Four Laws status, strike tracker, scope, and MCP connection status.\n\nClose with `Esc` or `q`. Scroll with `j`/`k`.\n\n## MCP Bridge\n\nWhen the Go MCP server is available, the extension can proxy calls to it for enhanced enforcement:\n\n1. Configure the server endpoint in `config.json` under `mcpBinaryPath` (URL for SSE, command for stdio)\n2. Initialize a session with `guardrail_init` — the extension auto-connects\n3. Use `guardrail_mcp` with an `action` parameter to call any MCP server tool\n4. Reconnection uses exponential backoff (1s base, 30s max, 5 attempts)\n\n## Storage\n\nAll state is stored under `~/.pi/agent/extensions/pi-guardrails/`:\n\n- `sessions/` — session state JSON files\n- `violations.jsonl` — append-only violation log\n- `.guardrails/regression/failure-registry.jsonl` — cross-session failure registry\n- `config.json` — user configuration\n\n## 22 Code Modules\n\nFileReadStore, ScopeValidator, StrikeCounter, HaltChecker, ViolationLog, SessionStore, InjectionDetector, OutputValidator, ContentFilter, CanaryTokenManager, PermissionManager, PolicyLoader, MCPClient, PreWorkChecker, FeatureCreepDetector, PatternRuleEngine, GitValidator, LanguageDetector, RegressionGuard, ExactReplacementValidator, SandboxRunner, GuardrailsPanel\n\n## CI/CD Integration\n\n### Pre-commit Hook\n\n```bash\ncp guardrails/pre-commit.sh .git/hooks/pre-commit\nchmod +x .git/hooks/pre-commit\n```\n\n### GitHub Actions\n\nThe `.github/workflows/pi-guardrails-ci.yml` workflow runs on PRs:\n- Unit tests for pi-extension and guardrails modules\n- Secret scanning on changed files\n- Scope compliance validation\n","readmeFilename":"README.md"}