Skip to content
Agentic Control Plane

Stop a force-push and ask before risky commands in pi

See, control, and price every tool call pi makes: bash, read, write, edit, and any custom tool. pi ships no permission system by design. This extension adds one, in one command.

Install

macOS · Linux · WSL
curl -fsSL https://agenticcontrolplane.com/install.sh | bash
Windows · PowerShell
irm https://agenticcontrolplane.com/install.ps1 | iex

The installer detects pi and puts the extension at ~/.pi/agent/extensions/acp.ts. It opens your browser once to set up a workspace and save the key to ~/.acp/credentials. Restart pi, and every tool call is checked from the next session.

MIT-licensed, zero dependencies, one readable file. Read it before you run it.

Why an extension is enough

pi keeps its core small: four tools, no approval prompts, no allowlist, no sandbox. Its docs say so. pi does have a typed extension system, and every tool call goes through it. pi has no MCP layer and no second tool path, so one extension sees everything the agent does. Codex needs hooks for shell and MCP for the rest, and some Cursor built-ins don’t emit events. pi needs one file.

How it works

pi sends every tool call through two typed events, and the extension listens to both:

pi event ACP endpoint What happens
tool_call POST /govern/tool-use The server returns allow, ask or deny. A deny blocks the call and puts the reason in the transcript. An ask blocks the call in pi and holds it for approval on the console Approvals page or from the approval email. Approve it, then ask pi to retry.
tool_result POST /govern/tool-output Output scanning. A server block turns the result into corrective feedback. A redact replaces what the model reads (PII, secrets, injected instructions).

That covers bash, read, write, edit, and subagent and custom tools. More detail is on the pi controls reference and the cross-harness matrix.

Approvals when nobody is watching

pi tells the extension whether a person is present through ctx.hasUI:

  • Attended (interactive TUI): an ask shows as a block in pi. Approve it on the console Approvals page or from the approval email, then ask pi to retry.
  • Unattended (pi -p, JSON mode): an ask becomes a deny, and the request appears in the console for later review. There is no timeout and no silent yes, so an agent nobody is watching cannot approve itself. This is the empty-chair posture.

A new workspace starts in audit mode, where everything is recorded and only the safety floor holds calls. The rules page lists what the floor holds.

If the gateway is unreachable

  • Attended sessions continue, loudly. The call proceeds, a [ACP] ⚠ UNGOVERNED warning shows, and a line lands in ~/.acp/lapse.log. The extension retries once first, because the slow answers are cold starts.
  • Unattended runs are blocked. Nobody is watching, so the block is the safety net.
  • Policy denies are unaffected. This only covers the case where the extension cannot reach the policy.

What gets installed and where

Path Purpose
~/.pi/agent/extensions/acp.ts The extension (global scope, so it loads without a project-trust prompt)
~/.acp/credentials Bearer token from browser sign-in (chmod 600)

The global path matters. Extensions there run before any repository is opened, while project-local .pi/extensions/ entries load only after you trust the project. To rotate the key, overwrite the credentials file. No reinstall is needed. To uninstall, delete acp.ts.

Manual install ```sh mkdir -p ~/.pi/agent/extensions curl -sf https://raw.githubusercontent.com/agentic-control-plane/pi-acp-plugin/main/index.ts \ -o ~/.pi/agent/extensions/acp.ts # then set your key: export ACP_BEARER_TOKEN="gsk_yourslug_..." # or write it to ~/.acp/credentials ``` Get a key at [cloud.agenticcontrolplane.com](https://cloud.agenticcontrolplane.com). Restart pi.

Add the cost X-ray

The extension sees tool calls, not the model call behind them. To price those, route pi’s model calls through the ACP proxy. Start pi with the launcher the installer put next to claude-acp and codex-acp:

pi-acp

The installer already wrote the acp provider into ~/.pi/agent/models.json and left your default model alone, so plain pi is untouched. pi-acp passes --model acp/gemini-3.5-flash for that launch only. ACP_PI_MODEL=<id> picks another. If the gateway is unreachable, it starts plain pi with a one-line note. The provider it writes:

{
  "providers": {
    "acp": {
      "baseUrl": "https://api.agenticcontrolplane.com/v1",
      "api": "openai-completions",
      "apiKey": "!cat ~/.acp/credentials",
      "compat": { "supportsDeveloperRole": false, "supportsReasoningEffort": false },
      "models": [{ "id": "gemini-3.5-flash" }]
    }
  }
}

By hand, that is pi --model acp/gemini-3.5-flash. The launcher adds only the gateway check. The proxy routes gpt-*, claude-* and gemini-* by model id and forwards unchanged. You get the same responses, now priced, with prompt-cache hit rates and the loop-vs-leaf split on the dashboard. Full walkthrough: Turn on Cost X-Ray.

Two things to know

  • pi needs Node 22+. Node 20 fails with confusing errors. Use fnm or nvm to select 22.
  • With no key, the extension says so at session start and then stays out of the way. A machine with no credentials is a clean no-op.

Learn more

Protected in 3 steps

Out of the box, ACP records every tool call your agents make. A short safety floor applies in every mode: catastrophic commands (rm -rf on your home or system folders, disk wipes) are always blocked, and force-push, destructive SQL, piping a download into a shell, and deleting outside your project are held for your approval. Your own rules (ask first / never) start applying when you turn on enforce. No rule can loosen the floor; a workspace owner or admin can switch it off on the Policies page (you were asked at install). With --local the always-blocked list is narrower: rm -rf on your home or root, disk wipes, fork bombs.

  1. 1
    Install. One command, then approve this machine in the browser. curl -fsSL https://agenticcontrolplane.com/install.sh | bash
  2. 2
    Turn on your rules. Run /acp-enforce in your agent. The starter rules start applying: rm and keychain reads are held for your approval (you approve on the console Approvals page or from the approval email); everything else keeps running and is recorded. Add your own with /acp-ask Bash.curl, /acp-deny Bash.git.push, /acp-allow Bash.npm, or on the Policies page. With --local there is no mode switch: the rules in ~/.acp/policy.json apply from the first call, and the starter file asks before rm, curl, git push, chmod and chown.
  3. 3
    See it work. Ask your agent to do something risky, for example git push --force on a scratch repo. ACP holds the call for your approval; the call and your answer land in the audit log (/acp-why for the last hold, the console Activity page, or ~/.acp/audit.jsonl with --local). In Pi, a held call shows as a block in the agent; approve it on the console Approvals page or from the approval email, then ask the agent to retry.

Copy-paste rules for the things people are most afraid of (force-push, prod database, rm -rf, a secret in a curl, overnight runs, a cost cap): Rules that stop the scary things.