pi-governance: The Harness You Can Actually Install

I wrote two posts about this problem. The first argued that harness engineering is replacing writing code as the core discipline of software. The second argued that the harness is where security enforcement actually belongs: not in prompts, not in model weights, not in sandboxes, but in the control plane sitting between the agent and the world.

The feedback I kept getting was the same: "Great, but what do I install?" Every team was building governance from scratch. Custom hooks, bespoke YAML, one-off audit scripts. The theory was clear. The tooling didn't exist.

So I built it. pi-governance is an open-source extension for Pi coding agents that ships enterprise-grade RBAC, DLP, bash command classification, human-in-the-loop approvals, and structured audit logging as a single pi install. It intercepts every tool call and enforces policy before execution. No custom hooks. No bespoke scripts. One extension, zero configuration to start, full customization when you need it.

Why this exists

AI coding agents have unrestricted access to your terminal, filesystem, and secrets. Without governance, an agent can run rm -rf /, read your .env files, pipe your AWS keys into a curl command, or exfiltrate API tokens through tool call outputs. There is no audit trail. There is no access control. There is no policy enforcement. The agent has root-equivalent permissions by default.

The previous posts framed this theoretically. The harness is the kernel; the model is a userspace process. Security belongs in the kernel. But kernels need to be built. pi-governance is the kernel implementation: a control plane that sits between the agent and every tool it tries to use, enforcing deterministic policy at every invocation.

The OpenClaw security "crisis" is a harness problem

OpenClaw has become the poster child for insecure AI agents. The headlines are brutal. CVE-2026-25253 (CVSS 8.8) allows total gateway compromise if an agent visits a malicious site. Censys tracked growth from 1,000 to over 21,000 publicly exposed instances in a single week. An independent study found 42,665 exposed instances, 5,194 actively verified as vulnerable, with 93.4% exhibiting authentication bypass conditions. The ClawHavoc campaign discovered 341 malicious skills in ClawHub (12% of the registry), later revised to over 800 (approximately 20%).^[1][2][3]

Gartner called OpenClaw "a dangerous preview of agentic AI, demonstrating high utility but exposing enterprises to 'insecure by default' risks like plaintext credential storage." Microsoft published guidance on running OpenClaw safely. CrowdStrike, Cisco, and Kaspersky all published warnings. The consensus is clear: OpenClaw is insecure.^[4][5][6]

The consensus is also wrong. Or rather, it's misdirected.

OpenClaw isn't insecure because the concept of an AI agent gateway is flawed. It's insecure because it ships without a harness. No RBAC. No DLP. No audit trail. No tool call interception. No bash classification. No human-in-the-loop. The agent gets credentials, tools, and network access with no governance layer between it and the world. Every vulnerability in the CVE list, every exposed instance, every supply chain attack follows the same pattern: an agent with unrestricted permissions doing something it should never have been allowed to do.

Look at CVE-2026-25253: an agent visits a malicious site, the primary auth token leaks, and the attacker gets full admin control. With pi-governance, DLP input scanning would catch the token pattern before it ever reaches the outbound tool call. Even if the prompt injection succeeds at the model level, the deterministic gate at the harness level blocks the exfiltration. The attack fails not because the model refused, but because the path doesn't exist.

Look at ClawHavoc: 800+ malicious skills in the registry executing arbitrary code. With pi-governance, every bash command goes through the 60-pattern classifier. Dangerous commands are blocked. Suspicious commands require human approval. The malicious skill can request curl | bash all it wants; the classifier denies it before execution.

Look at the 93.4% authentication bypass rate on exposed instances. With pi-governance, every session starts with identity resolution. No identity means analyst role: read-only, supervised, no bash, no write access. The agent can't do anything dangerous because the default is locked down.

The security community is framing this as "OpenClaw is insecure" when the accurate framing is "OpenClaw ships without a harness." These aren't the same claim. The first implies the architecture is fundamentally broken. The second implies it's missing a layer that should be standard. Every web framework was "insecure" before OWASP, WAFs, and CSP became standard. The framework didn't change. The ecosystem around it matured. Agent platforms need the same maturation: not better prompts, not bigger sandboxes, but governance infrastructure in the control plane.

pi-governance works with OpenClaw through a companion plugin (@grwnd/openclaw-governance) that bridges channel identity to governance roles. WhatsApp users, Discord users, Slack users each map to roles via YAML. The governance extension intercepts every MCP tool call flowing through the Pi runtime, regardless of which channel originated it. Same RBAC, same DLP, same audit, same HITL. The agent gateway becomes a governed agent gateway.

# Install for OpenClaw deployments
openclaw plugins install @grwnd/openclaw-governance

Install

One command:

pi install npm:@grwnd/pi-governance

That's it. Out of the box, you get:

• Role defaults to analyst (read-only) if no identity is set
• Bash classification active: 60+ patterns classified as safe, dangerous, or needs-review
• DLP active: 15+ secret patterns blocked on input, 5+ PII patterns masked on output
• Audit logging to ~/.pi/agent/audit.jsonl
• Supervised execution mode: every action requires approval

Zero configuration gives you a locked-down default. You open permissions up from there, not the other way around. This is the principle of least privilege applied to agent onboarding.

Set your identity

The extension resolves identity from environment variables, a local users file, or (coming soon) OIDC/SSO:

export GRWND_USER=alice
export GRWND_ROLE=project_lead
export GRWND_ORG_UNIT=engineering
pi

Or use the interactive config wizard to set everything up through a browser UI:

/governance init

The four pillars

pi-governance implements four capabilities that map directly to the harness security architecture from the previous posts. Each one addresses a specific failure mode that prompts, model weights, and sandboxes cannot handle.

Pillar 1: RBAC

Four built-in roles ship out of the box, each with scoped permissions:

Role	Tools	Execution	Budget
Analyst	read, grep, find, ls	supervised	100K
Project Lead	read, write, edit, bash, grep, find, ls	supervised	500K
Admin	all	autonomous	unlimited
Auditor	read, grep, find, ls	dry_run	50K

The analyst role is the default. If no identity is configured, the agent gets read-only access with supervised execution. This is the opposite of how most tools ship: wide open by default, security bolted on later. pi-governance starts locked and opens on explicit configuration.

Roles control three things: which tools the agent can invoke, which file paths it can access (via glob patterns with {{project_path}} substitution), and how many invocations it gets per day. When a project lead tries to access files outside their org unit's scope, the policy engine denies it before the tool ever executes. When the budget runs out, the session ends. No prompt engineering required; the path doesn't exist.

For teams that need more than YAML, pi-governance supports Oso/Polar as an alternative policy engine. Polar is a declarative authorization language that handles complex relational policies: multi-tenant access, cross-org-unit permissions, dynamic attribute-based rules. The YAML engine handles 90% of use cases. Polar handles the rest.

Pillar 2: DLP

Data loss prevention scans in two directions. On input, it blocks secrets from being passed into tool calls. On output, it masks PII before results reach the user or downstream systems.

The built-in scanner detects 15+ secret patterns (AWS keys, GitHub PATs, Anthropic/OpenAI API keys, JWTs, private key headers, database connection strings) and 5+ PII patterns (SSNs, credit cards, emails, phone numbers, IP addresses). Each detection can trigger one of three actions:

• audit: log the detection, take no action
• mask: replace sensitive data with a placeholder, partial reveal, or hash
• block: deny the tool call entirely

The directional scanning matters. When an agent tries to pass an AWS secret key as a bash command argument, the input scanner blocks it before execution. When a tool returns output containing a customer's email address, the output scanner masks it before the agent or user sees it. These are two different attack surfaces with two different mitigations.

# governance.yaml
dlp:
  enabled: true
  on_input: block      # secrets never reach tool execution
  on_output: mask      # PII never leaves the session
  masking:
    strategy: partial  # show first/last 4 chars
    placeholder: '***'
  custom_patterns:
    - name: internal_api_key
      pattern: 'grwnd_[a-zA-Z0-9]{32}'
      severity: critical
      action: block

Custom patterns let organizations define their own sensitive data formats. If your company uses acme_sk_ prefixed keys, add a pattern. If your compliance team needs to flag internal project codes, add a pattern. The built-in patterns handle the universal cases. Custom patterns handle yours.

Pillar 3: Audit

Every tool call, every denial, every approval, every DLP detection is logged as a structured event. 17 event types cover the full lifecycle:

Category	Events
Session	session_start, session_end
Tool Calls	tool_allowed, tool_denied, tool_dry_run, tool_result
Policy	bash_denied, path_denied, budget_exceeded
Approval	approval_requested, approval_granted, approval_denied
DLP	dlp_blocked, dlp_detected, dlp_masked
Config	config_reloaded

Each audit record includes: timestamp, session ID, user, role, org unit, tool name, summarized input, decision, reason, duration, and role-specific metadata. At session end, a summary aggregates all statistics: invocations allowed vs denied, approval counts, DLP detections, budget consumption.

Audit events flow to one or more sinks:

• JSONL (default): local file at ~/.pi/agent/audit.jsonl
• Webhook: HTTP POST to your SIEM, Splunk, or compliance system with retry logic
• Postgres: direct database logging for centralized audit storage and querying

This is the audit trail that doesn't exist without a harness. When a compliance team asks "what did the AI agent do in production last Tuesday," the answer is a structured query against the audit log, not a shrug.

Pillar 4: Human-in-the-loop

Three execution modes control how much autonomy the agent gets:

• autonomous: agent executes without approval (admin role)
• supervised: specific tools require human approval before execution
• dry_run: all tool calls are logged but none execute (auditor role)

In supervised mode, when a project lead's agent tries to run a bash command, the CLI prompts for approval with a configurable timeout (default: 5 minutes). If the timeout expires, the action is denied. For teams that need async approval flows, webhook mode sends an HTTP POST to an external system (Slack bot, Jira automation, custom approval service) and waits for a response.

The key insight: HITL is not about blocking every action. It's about requiring human judgment for the actions where the cost of failure is high. An analyst reading files doesn't need approval. A project lead running git push --force does. The granularity is per-tool, per-role.

Bash classification

The bash classifier is where the rubber meets the road for agent security. Every bash command the agent tries to execute is classified against 60+ regex patterns into three categories:

• safe: file viewing, directory listing, git status, text search, system info
• dangerous: rm -rf, sudo, disk operations, remote code execution, network modification, privilege escalation
• needs_review: commands that are context-dependent and require human judgment

The classifier handles multi-command inputs correctly. Pipes, semicolons, && and || operators are parsed while respecting quoted strings. A command like echo "rm -rf" | grep pattern is classified as safe because the rm -rf is inside quotes, not an actual execution. But echo hello && rm -rf / is classified as dangerous because the second command is real.

Roles can override patterns. An admin might need sudo for legitimate infrastructure tasks while a project lead should never have it. The base classification provides the floor; role overrides provide the customization.

How it maps to the theory

In The Harness Is the Security Layer, I laid out five harness security components. Here's how pi-governance implements each:

Deterministic gates are RBAC policy checks, bash classification, and DLP scanning. These are pure functions. They don't guess, don't hallucinate, and don't get prompt-injected. A blocked tool stays blocked regardless of what the agent says.

Context as least privilege is role-scoped tool and path access. An analyst can't see write tools. A project lead can't access paths outside their org unit. The agent doesn't need to be told not to touch production; the production path is structurally unreachable.

Architectural constraints are org-unit boundaries and path scoping with glob patterns. These encode your organization's structure into enforceable policy: the compliance team runs in dry_run mode, the platform team gets a longer approval timeout, the infrastructure team gets admin access.

The feedback loop is the audit system. Every denial is a logged, queryable event with a reason. When an agent gets blocked, the audit record tells you exactly why: which policy, which role, which tool, which input. This is security telemetry, not a black box.

Continuous compliance is config hot-reload and budget enforcement. Policy changes apply immediately without restarting sessions. Budget limits enforce daily usage ceilings. The governance posture adapts in real time.

How it helps: DLP, audit, governance

These three capabilities address different stakeholders with different concerns, but they all share the same enforcement point: the tool call boundary.

DLP is for the security team. Their question: "Can the agent exfiltrate sensitive data?" Without DLP scanning, an agent can read a .env file containing AWS credentials and pass them as arguments to a curl command. The input scanner catches the AWS key pattern and blocks the tool call before execution. The output scanner catches customer PII in tool results and masks it before it enters the agent's context. The security team gets a dashboardable stream of dlp_blocked and dlp_masked events.

Audit is for the compliance team. Their question: "What did the agent do, when, and who authorized it?" Every tool call produces a structured record: user identity, role, tool name, summarized input, decision (allowed/denied/dry_run), reason, timestamp. Session summaries aggregate per-session statistics. These records flow to JSONL files for local analysis, to webhooks for SIEM integration, or to Postgres for centralized querying. When the auditor asks for last quarter's agent activity, the answer is a SQL query, not a forensic investigation.

Governance is for engineering leadership. Their question: "How do we give agents real permissions without losing control?" RBAC provides the access model: who can do what. HITL provides the approval flow: which actions need a human sign-off. Execution modes provide the trust spectrum: from dry_run (observe only) through supervised (approve specific actions) to autonomous (full delegation). Org-unit overrides let different teams operate under different policies. Token budgets prevent runaway agent sessions. The governance posture is codified in YAML, version-controlled, and auditable.

Configuration

Config files are checked in order: $GRWND_GOVERNANCE_CONFIG (env var), .pi/governance.yaml (project-local), ~/.pi/agent/governance.yaml (user-global), then built-in defaults.

A minimal project config that gives the engineering team project lead access with custom DLP:

# .pi/governance.yaml
auth:
  provider: env
  env:
    user_var: GRWND_USER
    role_var: GRWND_ROLE
    org_unit_var: GRWND_ORG_UNIT

hitl:
  default_mode: supervised
  approval_channel: cli
  timeout_seconds: 300

audit:
  sinks:
    - type: jsonl
      path: ~/.pi/agent/audit.jsonl
    - type: webhook
      url: https://audit.yourcompany.com/api/v1/events

dlp:
  enabled: true
  on_input: block
  on_output: mask
  custom_patterns:
    - name: company_api_key
      pattern: 'acme_sk_[a-zA-Z0-9]{40}'
      severity: critical
      action: block

For the full schema reference and advanced options (Oso/Polar policies, Postgres audit sinks, org-unit overrides, webhook approvals), see the documentation.

The request flow

Every tool call goes through the same pipeline:

After execution, the result goes through DLP output scanning (masking PII) and result logging before being returned. At session end, a summary event captures aggregate statistics.

Every step that blocks produces an audit event with the specific reason. The agent doesn't just get a generic "denied." It gets "bash_denied: command matches dangerous pattern 'sudo'" or "dlp_blocked: AWS secret key detected in tool input." Diagnostic precision, not opaque rejection.

The standardization problem

In the harness engineering post, I flagged standardization as an unsolved problem: "Every team is building harnesses from scratch. There's no shared framework, no standard toolchain, no common vocabulary."

pi-governance is a direct response to that. It provides:

• A standard vocabulary (roles, policies, audit events, DLP patterns)
• A standard configuration format (governance.yaml + governance-rules.yaml)
• A standard audit schema (17 event types, consistent field structure)
• A standard extension point (custom patterns, Oso/Polar for advanced policies)
• Example configurations for common scenarios (startup, enterprise, compliance, SaaS)

The "service template" problem Bockeler identified -- where harness templates get forked and diverge -- is addressed through the config hierarchy. Organizations maintain a global ~/.pi/agent/governance.yaml for baseline policy, then layer project-specific overrides via .pi/governance.yaml in each repository. The base policy stays in sync. The project customizations live where they should: next to the code.

What's next

pi-governance v1.7.0 ships everything described here. The roadmap includes:

• OIDC/SSO identity: Okta, Google, Auth0 integration for enterprise identity resolution
• Sandboxed bash execution: firejail/bubblewrap containment for approved commands
• Slack bot approvals: webhook-based HITL through Slack for async team workflows
• Policy analytics dashboard: visualize denial patterns, DLP detections, role usage
• Agent-to-agent governance: policy propagation when agents spawn sub-agents

The extension is open source under Apache-2.0. Install it, try the defaults, customize the YAML, and read the audit logs. The harness isn't a theoretical concept anymore. It's a thing you can install and point at your agent today.

pi install npm:@grwnd/pi-governance

GitHub | Documentation | npm