
I Thought skep Had a Policy Engine
skep is my open-source, local-first supervisor for AI coding agents: it can run Claude Code, Codex, Aider, pi or its own built-in worker in a sandbox, re-runs your tests itself, and by default holds the patch until you approve it. You install it with pipx install skep.
The short version:
- skep’s policy was decided in five places that disagreed on 6 of 19 test probes, and the three most dangerous actions in that test got no approval card.
- One function,
decide(), now answers for the API, the CLI, the Claude Code hook, the editor proxy and the chat assistant, and “no rule matched” now usually means ask a human, not deny. - 46 of my 57 coding runs had no sandbox. From 1.5.0, new projects are sandboxed by default when the host supports it.
- The worker reported “passed” 112 times. skep could replay 50 of those and confirmed 48.
- The sharpest finding: of the 25 patches I approved by hand, I approved 20 in under ten seconds. The human in the loop needs better evidence on the card.
In July I wrote on this blog that governance is the product. I believed it. I had allowlists, approval cards, a sandbox, and a supervisor that re-ran the tests itself.
In November I went looking for the place in the code where a tool call gets decided. I found five places. They did not agree with each other.
This post is the update on skep since launch, and it is mostly about that one finding: what my own records said, what I built instead, how it works, and where it stops. That July post said “I won’t map the internals here.” This one does.
Version note: this describes skep 1.4.2 and 1.5.0, which was tagged the day I wrote it. Two things below exist only from 1.5.0 on, and I mark them. The numbers come from the run store and decision log on one machine, read on 19 November 2026; the queries and a sanitized copy of the data are at the end.
The record that embarrassed me
Three things from skep’s own store, on my own machine.
There was no single policy. An audit against the real model showed five decision paths, each reading a different subset of the policy layers, each with its own private answer for “no rule matched.” Asked the same question, they disagreed on 6 of 19 kinds of probe. The three most dangerous actions in that test session — a money transfer through an MCP tool (a tool served over the Model Context Protocol), a private file passed to web search, and a fetch grant for a whole host — produced no approval card at all. Meanwhile about 9 of the 23 cards that did appear were noise. It is all written down in ADR 0059, one of the architecture decision records (ADRs) in the skep repo.
Most of my coding runs had no sandbox. Of the 57 coding runs in my store, 46 ran in workspace mode: skep’s built-in worker, checked on every tool call but with no OS wall around it. Count every run in the store, early experiments and script runs included, and it is 121 of 198. The setup defaults said workspace, projects inherited it, and my own quickstart told people to type it. The fix (ADR 0066) makes new projects sandboxed whenever the host can sandbox, and leaves existing projects as they are. The ADR counted 41 of 49 a day earlier; eight runs later it is 46 of 57. The fix is in 1.5.0 and not in 1.4.2 or earlier.
The worker reported “passed” 112 times. skep confirmed 48. skep re-runs a project’s check on a clean copy after the worker finishes. My store has 112 of these records, and the worker reported a pass in every one. In 35 there was no patch, so nothing to check. In 27 the worker said it had changed files but left no patch to check. Of the 50 that skep could replay, 48 passed and 2 failed.
None of this is a story about a bad model. The agents did competent work. This is a story about me believing I had a control because I had written code that looked like one.
That is my honest answer to “why is governance required.” Not because agents are dangerous. Because without the same rules everywhere a decision is made, a record of what was decided, and a plain account of where the system can actually step in, you cannot tell whether you are governing anything.
Why “it asks first” is not governance
The usual answer is that the agent asks before it does something risky. Two things I saw on the wire say otherwise.
First, the agent may not ask at all. An editor drives Claude or Codex through an adapter, and the adapters’ default modes are auto and agent. In those modes the agent runs its tools and reports afterwards. Nothing is asked, so nothing can be answered. Even in their asking modes, both run commands like git status without asking.
Second, when an agent does ask, somebody has to read the question properly. skep’s old matcher looked at the first word of a command. It allowed this line because ls was on the list:
ls -la; rm -rf build
An agent asking permission is only governed if something other than the agent decides the answer, reads the whole question, and writes the answer down.
One function decides
So the REST API, the CLI, the Claude Code hook, the ACP proxy (the Agent Client Protocol, which editors use to drive agents), and the chat assistant’s file, shell, web and MCP checks now share one decide(). That is one function for those entry points. skep’s built-in worker checks its own tool calls against permissions compiled at dispatch instead, and some agent actions are never seen at all; the table further down says which. It takes a scope, an action and a value, and it checks in a fixed order:
tool call → (scope, action, value)
e.g. shell · run · "uv run pytest; rm -rf build"
│
1 FLOOR git push / fetch / commit, branch switches, sudo,
│ rm -rf /, reading ~/.ssh or .env ──► DENY
│ (checked first; no rule can lift it)
▼
2 BASELINE none approved yet ──► ASK
│ approved file was edited ──► ASK
▼
3 LAYERS the repo's policy, or your own operator policy:
│ template · group · project · your earlier approvals
│ a chained line is split; the strictest part decides
│ in a layer the most specific rule wins;
│ across layers deny > a named ask > the rest
▼
4 UNMATCHED no rule said anything ──► ASK (usually)
▼
5 TIGHTEN role, then the limits of whoever dispatched
│ you, then the private-data guard (chat only)
▼
VERDICT allow · ask · deny, plus the layer that decided
└──► decision log
Here is that example run for real, on skep 1.5.0 with the stock builder baseline and a freshly set-up project, trimmed to the fields that matter:
skep policy why <repo> shell run "uv run pytest; rm -rf build"
{
"run": {
"considered": [
{
"layer": "template:builder",
"pattern": "uv run pytest",
"rule_id": "shell:uv run pytest",
"verdict": "allow"
}
],
"decided_by": "default/unmatched",
"verdict": "require_approval"
}
}
Read it against the diagram. Step 1: the floor has nothing to say about either command. Step 2: a baseline is approved and intact. Step 3: the line is split in two, and uv run pytest matches an allow in the builder template while rm -rf build matches nothing. Step 4: the part nothing matched asks, and the strictest part decides the whole line. So the verdict is “ask”, credited to default/unmatched and not to the allow that was considered. Swap the second command for git push and step 1 ends it: deny, by the floor, with nothing considered.
A few of these deserve a sentence.
The floor comes first. Before any rule is considered, every part of a command line is checked against a short list that nothing can grant: remote git, commits and branch switches, privilege escalation, the catastrophic deletes, reads of credential paths. I ran the function against the obvious dodges while writing this. ls && git push, sh -c "git push", eval git push and git -C /tmp push are all denied.
A chained line is decided one command at a time. uv run pytest; rm -rf build comes back as “ask” even when uv run pytest is allowed, because the strictest part decides. Text the matcher cannot read at all — $(...), sh -c '...' — can never be allowed by a rule. The floor and the deny rules still apply to whatever they can read in it; otherwise it asks.
“No rule matched” now means ask a human. That holds for the hook, the governor and the chat assistant, with three named exceptions: a shell command the chat assistant wants to run inside a registered repo is still denied, a tool call classified as read-only runs, and a project you have explicitly unlocked lets its sandboxed worker’s default shell asks through. If skep itself cannot decide — a broken store, a missing file — the hook asks too. Where there is no human to ask, anything short of an allow is refused.
The baseline is locked. When you run skep onboard you approve a policy template. skep writes it read-only and stores its hash beside it. If its contents change afterwards, the guard asks on every call until you approve it again (and refuses outright on the governor’s hard path, where there is nobody to ask), and new runs are refused. A fresh install with no baseline asks about everything the floor does not refuse and you have not already approved.
Step 5 only tightens. A role is a named set of limits for a chat or a worker, and it can narrow a verdict but never widen it. A worker’s permissions are held to what its dispatcher may do, and where the dispatcher would have had to ask, the worker does not get it on its own: the question goes to a human, or the permission is dropped. There is one known gap: the worker matches command prefixes, so a dispatcher rule narrower than the prefix — allow npm, deny npm publish — is invisible to it. And a chat that has both read private data and taken in outside content has to ask before it sends anything out, even where a rule allows it.
Governing agents I did not launch
This is the part that is new in kind, not just in quality. As of this autumn there are two ways to put the same decide() in front of an agent skep did not start.
The Claude Code hook. One entry in Claude Code’s settings runs skep policy hook before every shell, file-edit and web call. skep answers allow, ask or deny, and Claude Code obeys.
The ACP governor. Editors and agent apps that speak the Agent Client Protocol spawn an agent as a subprocess. You give them skep acp govern -- <agent command> instead, and skep sits on the wire between them. One caution before the picture: in my setup skep answers only when the agent asks, so this is advice, not a wall.
client (editor) skep acp govern agent (Claude / Codex)
│ ── prompt ──────────►│────── relayed ──────────►│
│ │◄── "may I run │
│ │ rm -rf build?" ──────│
│ │ decide() → ask
│◄── forwarded ────────│
│ human: allow once ──►│────── answer ───────────►│
│ │
│ │◄── "I ran git status" ───│ (never asked)
│ │ logged as "observed"
That is an agent in an asking mode. Where skep can answer, it answers before the client ever shows a card, and the rest reach you. It never answers “always allow” on your behalf; a standing grant is a policy change, and you make those yourself. A call the agent runs without asking shows up only if the agent reports it.
The decision log shows governor activity on two days.
Here is the part I have to be exact about. These paths do not enforce the same thing:
| Path | Decides each call? | Can it block? | Wall behind it |
|---|---|---|---|
| skep’s built-in worker | Against permissions compiled at dispatch | Yes, every tool call | OS sandbox — in sandbox mode only |
| Claude Code, Codex, Aider or pi as a worker | No | No — only the sandbox does | OS sandbox, always |
| Claude Code hook | Yes | Deny or ask | None — it is your real shell |
| ACP governor, advisory | Only when the agent asks | Only what it was asked | Whatever the client provides |
| ACP governor, hard | Yes, for file writes and terminals | Yes — only an allow passes | Whatever the client provides |
The hard path only exists on version 1 of the protocol, and only when the client runs the agent’s file writes or terminals itself, so there is a hop for skep to stand on. T3 Code, the editor I use, does not, so there the governor is advisory only. In that setup an agent left in its out-of-the-box mode (Claude’s auto, Codex’s agent) asks nothing, so the governor only watches what the agent reports. What it gives me there is a record, not a wall. I think a record is worth having. I do not think it should be called enforcement.
The log answers “why”
Every recorded verdict names the layer and rule that produced it, and goes into a local log. Recognised credential patterns are masked; treat the log as sensitive anyway. And skep can tell you what the current policy would decide for a request you describe:
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",
"verdict": "deny"
}
}
considered is empty because the floor answered before any rule was considered.
The log is also how I found out my first policy was bad. Its first three weeks hold 319 denials from one rule, default-deny. 316 of them came from the Claude Code hook, nearly all on two days. They were not attacks. They were mostly an agent doing ordinary work — cd somewhere, grep something, pipe it to head — and being refused, because at the time “no rule matched” meant deny.
A policy that refuses ordinary work teaches you to turn it off. My Claude Code user settings do not list the hook today.
That is why unmatched now means ask. Since the change, the log on this machine holds 104 approval-required verdicts, 84 allows and 3 denials — all from skep’s own assistant and its dispatches. For 25 of the 104 the permission was dropped from a dispatched worker instead of being asked. The hook and the governor have logged nothing since 9 November, so I cannot yet show you the new default working on them.
I will not tell you the log shows disasters prevented. It doesn’t. The floor fired 11 times, mostly on remote git, and I cannot show that any of those was a real save and not a probe or a test. What the log shows is that every decision has a reason I can read. That is a smaller claim, and it is the one I can back.
What I got wrong on this blog
Four earlier claims need correcting.
-
“Every shell command executed” is in the audit trail (launch post). True for the commands skep’s built-in worker launches through its shell tool. For Claude Code, Codex, Aider and pi running as workers, skep keeps the evidence for each run — the command it launched, the sandbox profile, the patch, the re-verify — and not each tool call the agent made inside the sandbox.
Today: unchanged in 1.5.0, and the 1.5.0 README now says so plainly.
-
“Every action a worker wants to take passes through a policy layer”, and a domain controller that “makes carelessness impossible” (journey post). For those external engines there is no per-action check; the sandbox is the only wall. And “impossible” was wrong on its face: 46 of my 57 coding runs had no sandbox behind the checks.
Today: the correction still holds in 1.5.0. The external engines get no per-action check, the sandbox is their wall, and they always run in one. What changed is the default: from 1.5.0, new projects run sandboxed whenever the host can sandbox (ADR 0066). Existing projects keep the mode they had.
-
“Every MCP call passes through the same governed policy layer” (launch post). It didn’t. MCP calls read only part of the policy plus a risk guess based on the tool’s name. That is how the transfer above got through without a card.
Today: fixed since 1.4.0, so fixed in 1.5.0. The chat assistant’s MCP calls go through the same
decide(), baseline included, in place of the old name-based risk ladder. What is still open is under “Where it still stops”: whether a call counts as read-only is partly the tool’s own word. -
The launch quickstart used
--execution-mode workspace. That mode has no sandbox. I should not have led with it.Today: the 1.5.0 README quickstart uses
--execution-mode sandbox.
Where it still stops
- Not everything goes through
decide()yet. The permissions compiled for a dispatched worker, and a few smaller checks, still read the policy on their own path. The ADR lists them as open. - Reads are mostly open. In sandbox mode, writes are confined to the run’s worktree and a few designated folders. Reads outside it are not confined, apart from a list of credential paths. The Claude Code hook has no opinion on the
Readtool at all, socat ~/.ssh/id_ed25519is denied and aReadof the same file is never seen. - The floor catches what it can read.
python deploy.pycan rungit pushinside the script, and a word matcher never sees it. Ifpython deploy.pyis allowed, whatever is inside it runs. A sandboxed worker has a wall behind that. The hook has nothing. - “Read-only” is partly the tool’s own word. An ordinary MCP tool call counts as read-only when its server marks it that way, its name starts with a read verb, and no mutation verb appears anywhere in the name; browser tools go by a short list of name keywords instead. Either way, skep does not check what the tool actually does, so a wrong or dishonest server can get a call through without a card.
- The governor does not sandbox and does not verify. It governs the wire.
- Verification is as strong as the command you pin. A thin check confirms a bad patch. From 1.5.0 skep refuses to auto-land on the obviously empty ones, like
true, but it cannot tell a weak test suite from a good one. And installing dependencies for the re-run can execute a patch’s build code before you have approved anything. - I approve my own baseline, and I approve fast. Across 46 patch-approval records, 13 were approved automatically after a confirmed re-verify and 25 I approved by hand — 20 of those within ten seconds. Eight ended denied: three by me, the rest stale, redundant or failed to apply. All three of mine were patches whose re-verify had passed. That is the best argument I have for keeping a human in the loop, and the ten-second figure is the best argument that the human needs better evidence on the card.
- It is one operator on one machine. The decision log has entries on 9 of the last 29 days, and the governor on 2. This is early field data, not a track record.
The threat model has not changed: the agent is competent and untrusted. A kernel exploit is out of scope.
What I’d tell July me
Governance is not the list of features. It is whether the same rules decide everywhere, whether you can read what they decided, and whether you know where the system can actually step in.
I had the features in July. I got the rest in November, and I only found out it was missing because I asked the system to explain itself and got five different answers.
If you run coding agents and want to see what yours are doing, the governor and the hook are the cheapest way in. You can try them without dispatching a single worker; run skep onboard first, so there is an approved baseline to answer from.
Here is the setup I use. The client is T3 Code: add a Local ACP command provider and paste what skep acp install-hint prints, which wraps Claude’s ACP adapter in skep acp govern. Then put Claude in its default mode. That is an asking mode, so the governor answers on the advisory path. Leave Claude in auto and the governor only watches.
- The ACP governor
- The Claude Code policy hook
- The invariants — the file I most want challenged
GitHub: github.com/Anmolnoor/skep
How I counted
These numbers come from my own store, so you cannot re-derive them from the repository. You can do two things instead: run the same queries on your own store, or recount mine from the sanitized copy below. The store is ~/.skep/supervisor/supervisor.sqlite3 and the decision log is ~/.skep/supervisor/audit/policy/decisions.jsonl.
-- runs by kind and mode (46 of 57 coding runs; 121 of 198 overall)
SELECT worker_kind, execution_mode, count(*) FROM runs GROUP BY 1, 2;
-- what the worker reported against what skep's replay found (112 records)
SELECT worker_outcome, outcome, count(*) FROM reverifications GROUP BY 1, 2;
-- patch approvals: who resolved them, and how many within ten seconds
SELECT status, resolved_by, count(*),
sum((julianday(resolved_at) - julianday(requested_at)) * 86400 < 10)
FROM approvals WHERE action = 'apply_patch' GROUP BY 1, 2;
The decision-log figures are counts of rows grouped by verdict, rule_id, source and the first part of actor. Eight rows written by a tamper test are in the totals; none of them is among the hook’s 316 denials.
The data. Four CSV files, one row per record, covering everything up to the end of 19 November 2026 (UTC):
- runs.csv — 198 rows: day, worker kind, engine, execution mode
- reverifications.csv — 112 rows: day, what the worker reported, what the replay found
- approvals.csv — 46 patch approvals: day, status, human or automatic, seconds to resolve, why a denial was a denial, whether the replay had passed
- decisions.csv — 565 rows: day, kind of actor, scope, action, source, verdict, rule, layer, and whether a delegated ask was passed on or dropped
They are sanitized, which means reduced to categories. There are no command lines, paths, hosts, URLs, repo or project names, ids or notes in them, and times are cut to the day. A rule that named a command or a host appears only as its class (shell:*, net:*), and the test rows are labelled test. The run-store and decision-log counts in this post reproduce from those four files, and the script that wrote them checks them before it finishes. The 6-of-19 and 9-of-23 figures are ADR 0059’s, not mine to recount.
The mechanism. The numbers are mine, but the behaviour is checkable by anyone. On skep 1.5.0, against a throwaway home with the builder baseline:
skep policy decide shell run "git push" --repo <repo> # deny, by the floor
skep policy decide shell run "ls -la; rm -rf build" --repo <repo> # ask, unmatched
skep policy decide shell run "uv run pytest" --repo <repo> # allow, template:builder
skep policy why <repo> shell run "git push" # which layer decided
Those are the answers I got. Note that decide writes a row to your decision log each time and why does not. The four test files that cover this — the policy engine, the hook, the governor and the sandbox default — pass at the 1.5.0 tag.
Holes poked in any of the above are the most useful thing you can send me.