claude-projects/agent-builder/agent_sudo_vs_sudo_bridge.md

# Agent-Sudo vs. the old sudo-bridge — what actually got better

Written 2026-07-08. Companion to `agent_sudo_design_decisions.md` (design, D1–D10) and the P0–P5 build prompts in `agent_prompts.md`.

Your instinct — *"more elaborate and complicated, but more eloquent and better-suited"* — is right, and here's the precise reason: **the extra machinery all buys back a single thing the old bridge could never have — safety WITHOUT a human in the loop.** The old bridge tried to be safe by *asking you*. Agent-Sudo is safe by *construction*. That's not a bigger version of the same idea; it's a different idea.

---

## The one-sentence difference
- **sudo-bridge:** "Run it if it's on a list; for anything risky, ping Kaleb and wait." → safety depends on you being awake, reachable, and able to judge the command.
- **Agent-Sudo:** "Run it if it's provably safe/reversible; test it if it's unknown; snapshot it if it's live; refuse it if it's catastrophic — and never ask a human to rubber-stamp what they can't evaluate." → safety depends on nothing human at runtime.

---

## Side-by-side

| Dimension | Old sudo-bridge | Agent-Sudo | Why it matters |
|---|---|---|---|
| **Risk model** | 3 states: refuse / auto / **ask-human** | 5 tiers: auto-safe / auto-reversible / **sandbox-first** / **snapshot+execute** / hard-refuse | The middle of the old model was "interrupt Kaleb." The middle of the new model is "prove it's safe by testing or snapshotting." Judgment moved from you to evidence. |
| **The human gate** | Tier-2 = NTFY approve/deny, 900s timeout | **Eliminated.** Only residual human touch = a rare Tier-4 hard-refuse | The gate was *broken* (you missed NTFYs → timeouts, ×5 agents) AND *theatrical* (you approved commands you couldn't vet). Removing it is the whole point. |
| **Unknown command** | Not on list → refuse (dead end) | Reproducible → **test in an Incus mirror**, read the audit, self-classify; if the sandbox lacks a dep, **add it to the rebuild script and retry** | The old bridge never learned. Agent-Sudo's allowlist self-completes from evidence. |
| **Autonomy when you're away** | Stalls on anything tier-2 | Runs every Tier 0–3 unattended; only *expanding* what's allowed waits for you | Automations don't freeze at 3am because you're asleep. |
| **Live-service ops** (docker/systemctl/DB) | auto or ask — no safety net | **Timeshift snapshot + scoped-undo captured BEFORE execute + auto-verify after** | A bad restart is recoverable by construction, not by luck. |
| **Rollback** | none (a tier-1 command just ran) | **scoped command-specific undo** captured pre-execution (file backup / package record / Jenkins redeploy) | Blast radius = only what the command touched. |
| **Host awareness** | one flat list, same on both | **per-host tiering** — primary is stricter; a command that's Tier-3 on server-01 can be Tier-4 (refuse) on primary | Production (Vault/Authelia/media/DB) gets a bigger no-go set than the test box. |
| **Security philosophy** | gate access (ask a human) | **constrain capability** (least-priv allowlist it *cannot widen itself*) + execute-vs-expand split | Compromising the smart brain inherits only "do already-safe things" — it can't reach arbitrary commands or Tier-4. |
| **Config integrity** | allowlist.json, root-owned file | **SUDO.md signed via Vault transit**, daemon verifies before load | The ruleset can't be silently widened; tamper = refuse + alert. |
| **Credentials** | daemon runs as root, no auth on the exec path | dumb root executor **+ scoped short-TTL Vault AppRole** (reads exactly one secret path) + AppArmor/seccomp/egress-lockdown | Auth-agnostic and least-privilege; survives your fingerprint→privacyIDEA→YubiKey roadmap without redesign. |
| **Anomaly response** | none | **self-disarming circuit-breaker** (abnormal rate/mix/failure → auto-stop Tier-3 + alert) + **dual-service concurrence** on Tier-3 | The autonomous replacement for a human panic button. |
| **Watchdog** | none | **Hermes** (separate process, no exec power) as independent monitor/second-opinion/tamper-detector — later layer | Separation of duties: Agent-Sudo has hands + no judgment, Hermes has judgment + no hands; they check each other. |
| **Training data** | executions logged, never used | every classify/test/execute/review → labeled row in `command_audit`; **AI-proposal → your review verdict = gold label** for the local model | The system gets smarter over time and feeds the local brain. |
| **Audit** | JSONL→Postgres, fail-soft (good) | same resilience **+ append-only, shipped off-box** | Even a full host compromise can't erase the trail. |
| **Deploy/lifecycle** | Coolify-managed | plain docker-compose via **Jenkins/Gitea** (Coolify retired) | No dependency on retired infra; fits the current stack. |
| **API contract** | `POST /exec` etc. | **identical** (drop-in) — `/approve` `/deny` removed | Zero caller changes; T2/T3 just add latency transparently. |

---

## What the old bridge did well (and Agent-Sudo keeps)
Not everything was wrong — these carry over unchanged:
- **Dumb root daemon + unprivileged brain** (separation of privilege) — kept and hardened.
- **Independent re-validation in the daemon** (defense in depth — the executor doesn't trust the brain) — kept.
- **Danger-pattern regex veto** — kept, now auto-routes to Tier-4.
- **fnmatch first-match-wins ordered list** — kept as the engine core, extended with per-host overrides + verb heuristic.
- **JSONL-first→Postgres fail-soft audit** — kept, extended to append-only/off-box + training fields.

So it's an **evolution of a known-good core**, not a rewrite — which is exactly why the build (P2) refactors the existing `app.py`/`daemon` rather than greenfielding.

---

## The honest cost of "more elaborate"
Agent-Sudo is genuinely more to build and run: an Incus sandbox substrate, a signed ruleset, a scoped-undo library, snapshot automation, an AI evaluator, a circuit-breaker, dual-concurrence. That complexity is real. But every piece exists to remove a human from the runtime path while *raising* safety — and the design deliberately **added no new external tool** (Incus, Vault, AppArmor, Timeshift, Jenkins already exist; Falco/OPA are parked as future options). The complexity lives in *our* code and config, not in new attack surface.

**Bottom line:** the old bridge's ceiling was "a human bottleneck that half-works." Agent-Sudo's floor is "safe, autonomous, self-improving, and it can't widen its own powers." It's not that sudo-bridge was bad — it's that it was solving the problem with the one ingredient (you, at runtime) we most need to remove.