The ACP governor
skep ships as a transparent ACP proxy — skep acp govern -- <agent command>
— that any ACP client spawns in place of the agent. It relays every
JSON-RPC message unchanged except the agent's permission ask, which it
answers from the same decide() every skep run uses, and what it cannot
decide it forwards to the human behind the client. Every verdict, every
tool call the agent ran unasked, and every answer the human gave lands in
skep's decision ledger (ADR 0054).
Install
The Air smoke — a new machine, this doc alone:
pipx install skep && skep onboard --template builder --yes
skep acp install-hint
A fresh install asks for everything (ask, reason no_baseline) until a
baseline is approved; a home from an earlier skep keeps deciding as before,
and skep doctor says how to approve one.
On Debian/Ubuntu (PEP 668, an "externally managed" system Python) use
pipx or uv tool install skep — never pip install into the system
Python. Either puts skep on your PATH. skep onboard connects a model,
registers a work directory, records the sandbox backend, and locks
builder as the policy baseline the governor answers from (see
onboarding.md; add --yes to take the defaults without
prompts).
Then ask the agent what it will do under skep:
skep acp doctor -- npx -y @agentclientprotocol/claude-agent-acp
The doctor sends initialize and a dry session/new (never a prompt) and
prints:
agent:the name and version the adapter reports;protocol:the ACP version it answered (v1orv2);preset:the mapper row it gets —generic (unknown agent: …)means skep has norawInputreader for it and every ask it cannot read is forwarded to you;modes:the modes the agent advertises, the default marked;rings:which rings can be live (see below);WARNING: default mode … never askswhen the default mode is one ofauto,agent,agent-full-access,bypassPermissions— in that mode skep only observes.
Do the same with npx -y @agentclientprotocol/codex-acp.
T3 Code
Settings → Providers → Add provider → Show more → Local ACP command.
The dialog takes an executable plus one literal argument per row, and T3
launches it directly — no shell, no PATH lookup — so the executable must be
an absolute path. skep acp install-hint prints exactly what to paste,
under one line naming the baseline the governor answers from (or, with none
approved, run skep onboard first — the governor answers from an approved baseline):
baseline: builder approved 2026-11-09T12:00:00Z sha256 0123456789ab
Local ACP command — claude-agent-acp
executable: /absolute/path/to/skep
arguments, one row each:
acp
govern
--
npx
-y
@agentclientprotocol/claude-agent-acp
and the same for @agentclientprotocol/codex-acp. Click Add argument
once per line: a row is one literal argument, so a single row holding
acp govern -- … reaches skep as one unrecognised word and the provider
reports "could not create a test session". Add one provider instance per
agent. With an adapter installed globally the last three rows become its
binary name (claude-agent-acp / codex-acp).
T3 respawns the agent after a thread goes idle and continues the same
session with session/resume (v2) or session/load (v1); the governor
binds that request's cwd as it does session/new's, and everything the
agent reports between that request and your next prompt is replayed
history — cached for joins, never recorded as observed rows. Claude's
adapter replays the thread on a resume too, as tool_call_update frames
carrying the original ids.
The two rings, honestly
- Advisory — the permission ask. skep decides
session/request_permissiononly when the agent's own mode chooses to ask. In Claudeautoand Codexagent(their defaults) the agent never asks, so skep only observes. Even in the asking modes (Claudedefault, Codexread-only) both adapters run read-only commands such asgit statuswithout asking; those becomeobservedrows. - Hard — client-mediated execution. Only on ACP v1, and only with a
client that advertised
fs.writeTextFileorterminalatinitialize: then the agent'sterminal/createandfs/write_text_filepass only onallow; anything else is a JSON-RPC error, because that hop has no human to forward to (A10). T3 advertises neither, so on T3 the governor is advisory only.
A demo policy
Bind a test repo to a project and give it a shell allow list:
-
Create a policy group holding the allow list. skep's CLI has no standing shell-allowlist write today; the group is written through the web UI (Policies page → policy groups → new group) or its REST route with the token
skep serveprints:curl -X PUT http://127.0.0.1:8765/api/policy-groups/acp-demo \ -H "x-skep-token: $TOKEN" -H 'content-type: application/json' \ -d '{"allowed_shell_commands": [["git","status"],["ls"],["pnpm","test"]]}'(From chat, the Queen's
allow_shell_commandwithrepo=writes the same grant into one project's list behind a confirm card.) -
skep project setup --strategy trusted_local_dev --group acp-demo <repo>.fs: workspaceis already granted by the strategy, so writes inside the repo are allowed.
What that policy answers:
| The agent asks for | skep's answer |
|---|---|
git status, ls, pnpm test |
allow (shell:<command>) |
| a write inside the repo | allow (fs: workspace) |
rm -rf build (unlisted) |
unmatched (ask) → forwarded: the human in T3 decides |
ls -la; rm -rf build |
unmatched (ask) → forwarded: a chained line is decided one command at a time, and rm is unlisted |
ls $(cat names), sh -c '…' |
unmatched (ask) → forwarded: text a prefix matcher cannot read matches nothing |
git push |
floor deny, before the client sees it |
A repo's run policy compiles allow lists only (allowed_shell_commands,
fs: workspace). There is no project-level deny rule for shell: "ask on
rm" means leaving rm unlisted, and the only explicit shell deny is the
floor (remote git, ADR 0044).
What you will see
The governor writes one line to the client's log at startup; it starts
with skep acp:, e.g.
skep acp: governing claude-agent-acp (ACP v2) — rings: advisory — home …
The agent's own stderr passes through to the same log. T3's approval card appears only for asks skep forwarded; allows and denies are answered before T3 sees them.
The ledger:
skep policy decisions --actor 'acp:*'
returns rows newest first, plus a summary that counts decisions by
verdict and observed/forwarded rows apart (they are not decisions).
Rows of the kinds a live session produces (trimmed):
{"actor": "acp:codex-acp", "scope": "shell", "action": "run", "value": "git status",
"source": "observed", "agent": "codex-acp"}
{"actor": "acp:claude-agent-acp", "scope": "filesystem", "action": "write", "value": "workspace",
"source": "run", "verdict": "allow", "decided_by": "dispatch/fs:workspace"}
{"actor": "acp:codex-acp", "scope": "shell", "action": "run", "value": "rm -rf build",
"source": "run", "verdict": "require_approval", "rule_id": "unmatched",
"decided_by": "default/unmatched"}
{"actor": "human@<client>", "scope": "shell", "action": "run", "value": "rm -rf build",
"source": "forwarded", "agent": "codex-acp", "outcome": "allow_once", "note": "unmatched"}
{"actor": "acp:codex-acp", "scope": "shell", "action": "run", "value": "git push",
"source": "floor", "verdict": "deny", "rule_id": "floor.worker-git-hard-denies"}
human@<client> is the client's own name from its initialize. Ask why
any one of them answered as it did:
skep policy why <repo> shell run "git push"
{
"floor": "remote git commands never run from chat — skep lands patches after approval; …",
"run": {
"considered": [],
"decided_by": "floor/floor.worker-git-hard-denies",
"rule_id": "floor.worker-git-hard-denies",
"verdict": "deny"
},
…
}
The floor answered before any document was read (considered is empty);
no grant, group or project overlay can change it.
Tracing the wire
Set SKEP_ACP_TRACE=/path/to/trace.ndjson in the provider's environment
(T3: the provider's Environment section) and the governor appends every
frame it relays, both directions, in the fixture envelope the tests use:
{"dir": "c2a", "raw": "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"session/load\", …}", "t": 1793997000.1}
Nothing is written without the variable. The file is the agent's and the
client's exact words — scrub paths and ids before sharing it — and
tests/fixtures/acp/ loads it unchanged, so a session that misbehaved
inside a client becomes a golden case.
What this does not do
- It does not sandbox the agent. T3 spawned it; T3's (or the agent's) sandbox is the wall. skep governs the wire (I12).
- It does not see tool calls the agent neither asks about nor routes
through the client. In Full access with an agent that runs its own
shell, skep observes
tool_callupdates and decides nothing. - It does not verify results. The G10 re-verify is a worker-landing concept (I1/I2) and nothing lands through the proxy. Verification of externally-driven sessions is a later ADR, if ever.
- It does not read or write T3 state. No T3 API, no T3 database, no pairing token.
skep never answers allow_always or reject_always (D6): a standing grant
is a policy write, made through skep's own faces with the tier named.
From a dev checkout instead of an install:
uv run --project /path/to/skep skep acp govern -- ….
See also cli-reference.md and
policy-hook.md.