Governing an AI Agent With Root on the Fleet: When the Approver Can't Read Code

Scope: the permission architecture governing AI coding agents across a self-hosted fleet: a written rulebook binding four different agent tools, plus a pre-execution policy hook with an extensive self-test suite, plus a three-tier allow/ask/deny permission config.

Problem

This infrastructure is built and operated through AI coding agents rather than by hand. That is what makes governance the hard problem: the agents don't just suggest changes, they can act on the machines directly, so the line between "an agent does useful work" and "an agent does something irreversible" has to be drawn in the tooling itself, not left to good intentions.

That produces a governance problem with an unusual shape. The standard answer to "how do you let an AI agent run commands safely?" is ask a human before each dangerous one. But this human cannot read the commands. An approval dialog showing a container-orchestration command against the production host conveys nothing to him. He can approve everything, in which case the gate is decorative, or deny everything, in which case nothing gets done. Either way, the approval step becomes a formality instead of a judgment call.

Two failure modes had to be avoided at once, and they pull against each other:

• Under-gating: an agent quietly changing production, using an administrator credential, or standing up infrastructure nobody decided to build.
• Over-gating: so many prompts that the human stops reading them, which converts every gate in the system, including the ones that matter, into a reflex click.

The second is more insidious. A gate that is always clicked through is worse than no gate, because it produces the documentation of oversight without the substance.

The model: three tiers, four absolutes, one provisioning gate

Tier 1: production and the shared node, a typed approval word. State-changing commands on either box run only after the operator types a specific literal word in chat, in reply to a plain-English what/why/impact.

Tier 2: the autonomous machines, run freely, but. Autonomy covers operating what already exists: restart, redeploy, update, roll back, edit a config file, read logs, read an application-scoped secret so that application can run. Four triggers escalate to a lightweight chat confirmation, not the full ceremony, even on an autonomous box:

1. A net-new service, container, or daemon that wasn't running before.
2. Writing to another service's database (records or schema).
3. Using an administrator or root-equivalent credential.
4. Onboarding a new machine, or new cross-machine wiring.

The stated rationale: these change the shape of the fleet, which is a decision the human holds, not routine operations. The rule exists because it was violated: an agent once stood up a monitoring daemon on a new box and registered it with the hub's admin credential, fully autonomously. Every mechanism it used was permitted; the composition was a fleet-shape decision it had no business making alone.

Tier 3: metered spend, a separate typed approval. Anything billing per token or per call needs its cost explained in plain English first.

The four absolutes at every tier: never run local privilege escalation; never push to the release branch; no force-push, recursive delete, SQL DROP, or volume removal; credentials never in chat.

And the rule that makes the tiers usable in practice, the one doing the most work of anything in the rulebook:

Before ANY action that will change a machine, a database, production, deployed state, or anything not trivially reversible, you MUST first explain in plain English, no jargon, in 2–4 short lines: WHAT it does in outcome terms (not command terms), WHY now, and IMPACT if it's wrong plus whether it can be undone.

If he can't tell what something does from your explanation, that's on the explanation: rewrite it simpler, don't just proceed.

The method that actually fixed things: replay, don't reason

Prompt fatigue was raised five separate times. The first four responses were behavioral promises and config tweaks reasoned from reading the policy. None worked, because reasoning about a permission engine tells you what you think it does.

The technique that worked: extract every shell command from the stored session transcripts, pipe each through the LIVE policy hook (importing the production script, so there is no classification drift), apply the allow/ask/deny rules in their real precedence order, and count what would prompt today.

Pass 1: 372 commands across 20 sessions:

The dominant cost was the agent's own mandated workflow step (the post-push "open a review request" API call) hitting an internal server on the private network. The real gates cost nothing. No amount of reasoning would have found that; it presented as a production-access problem and was an allowlist problem.

Pass 2, the very next day, because the complaint recurred:

Pass 1 had worked for what it targeted: the previously dominant call is entirely absent from both lists. The residual was a different population. Five defects, each probed live against the hook rather than inferred:

Result: day 1 replays 83 → 45 (−46%). The prior window goes 93 → 82 (−12%), and the small movement there is the correct outcome. Fifty of that window's residual prompts are real writes to production: policy alterations, in-place file edits, service restarts. That is the top-tier gate working exactly as designed, and nothing in the fix touched it. A prompt-reduction pass that had flattened that number would have been a regression dressed as a win.

Findings worth keeping

The gates live in more than one place and nothing keeps them in sync

Defect #1 generalizes. A machine had been built that morning and declared autonomous in the rulebook's machine table (committed, correct, documented). But a machine's tier is actually declared in more than one place, and only the prose was updated. Every command to that box gated all day: 40% of the day's prompts. The enforcement points are not derived from the machine table; nothing checks that they agree. The written rule and the thing enforcing it were allowed to disagree silently, and the failure mode was a full day of friction with no error anywhere.

Two holes were closed in the same commit as the loosenings

Asked "any risk with these fixes?", answering honestly surfaced two real openings the fixes would have created. Both were closed in the same commit rather than filed as follow-ups:

• Reach-through commands. Some commands name an allowed machine on their face but reach through it to a gated one. That case had been gating by accident, as a side effect of the parser bug, so fixing the parser without a guard would have opened it. That shape of command now gates unconditionally, even to an allowed host.
• Destructive sync flags. The hook already allowed the sync tool; only a redundant config entry was prompting. Removing that entry would have made a mirror-with-delete silent, which erases every file in the destination not present in the source. Delete flags now gate unconditionally.

Outcome

• A working three-tier model, enforced in code for one agent and in binding prose for the rest, with the prose treated as the primary artifact because enforcement varies by tool and the prose is the one thing all of them read.
• Measured prompt load down 46% on the worst measured day, with the production gates untouched and still costing zero false prompts.
• A policy hook with a large self-test suite, all passing, grown across each pass as fixes and mitigations were added, plus explicit negative cases (a command to an unknown host still asks; a lookalike domain crafted from a legitimate internal name still asks; a state-changing command to a gated box still asks).
• File-tool access narrowed to three directories, with private keys denied by exact name, and the limit of that scoping stated rather than oversold: it is one layer of defense, not a full sandbox, and it was never claimed as more.
• Guardrails confirmed holding against genuinely unattended agents: during headless job runs, a recursive delete was hard-denied, a job that went looking for credentials on its own initiative was denied, and the production machines were never touched.

Lessons

1. When the approver can't read the command, the explanation is the gate. The permission dialog is a backstop. The actual control surface is the plain-English what/why/impact written above it, plus the rule that a bad explanation is the explainer's fault, not the reader's.
2. Measure prompts by replaying transcripts through the live policy. Never reason from the config. Two passes, two dominant drivers (71% one internal API call, then 40% one missing machine), neither of which reading the policy would have surfaced. The complaint was a measurement request, not a preference.
3. A gate that is always approved is worse than no gate. It manufactures a record of oversight with none of the substance. Prompt volume is therefore a safety metric, not a UX metric.
4. Not all prompt reduction is progress. The window that barely improved was the one full of real production writes. Judge a tuning pass by which prompts survived, not by the total.
5. Ship the mitigation in the same commit as the loosening. Two of five fixes would have opened real holes: a tunnel into the gated box, and a silent recursive delete. Both were found only by answering "what's the risk?" honestly when asked, and neither was deferred.
6. Declare a machine's tier in one place, or accept that the copies will disagree. Multiple declarations with nothing reconciling them cost 40% of a day's friction, and will recur on the next machine unless the check is added to onboarding.