docs: "How Trinity keeps agents in bounds" — the guardrails vision page, and fix the two "agents cannot bypass" overclaims #3278

Problem

People keep asking "what is Trinity's approach to guardrails?" There is no page that answers it. agent-guardrails.md documents the in-container hooks and nothing else. Two sentences in the user docs also overclaim: they say agents "cannot bypass or edit" guardrails, but the agent user holds NOPASSWD:ALL in its own container (docker/base-image/Dockerfile already says the root-owned files stop accidental rewrites, not a deliberate agent):

• docs/user-docs/faq/security.md:71
• docs/user-docs/agents/agent-guardrails.md:3

What to build

1. A new user-docs article, "How Trinity keeps agents in bounds": the product's guardrails vision, written for operators, security reviewers and buyers. Put it under docs/user-docs/guides/ or wherever fits the docs IA best. Link it from agent-guardrails.md and the security FAQ.
2. Fix the two overclaiming sentences so they describe the in-container hooks as defence in depth against accidents, with the real boundary outside the container.

Source text for the article is below. Keep the voice and structure. Adjust the wording to the docs style.

Acceptance criteria

• The article exists, is in the docs nav, and is linked from agent-guardrails.md and faq/security.md.
• Every "available now" claim is true on main / the latest release, verified in code. Anything only on dev is marked "coming in the next release". Anything not built is marked "planned". Nothing is stated as shipped that isn't. Specifically:
  • gated skills only count as available once the approval map that switches them on exists
  • the credential vault is marked as an Enterprise feature
  • role-addressed approvers and the Inbox card are marked with their edition
• Per-runtime coverage is stated honestly: Claude Code, Codex and Gemini each say what holds.
• The two overclaiming sentences are corrected.
• (added 2026-10-06) docs/user-docs/agents/agent-runtimes.md no longer says read-only mode and credential redaction work the same on every runtime. It matches the new page's coverage table.
• (added 2026-10-06) docs/user-docs/faq/security.md: the answer to "Can an agent… remove its own guardrail hooks?" no longer opens with "No." It says the hooks catch accidents, the agent has passwordless sudo in its own container, and the boundary that holds is outside the container. It links to the new page.
• No internal project names, customer names, private-tracker links or internal URLs appear.

Source text

Trinity bounds agents by what they hold, not what they're told.

The bet. Companies don't hand real work to agents because they can't bound them, not because the agents lack capability. The usual answers are a prompt that says "please don't", a human approving every step, or a rigid workflow that throws away the judgment. None of these scale. We think delegation becomes routine when it is bounded the way a job is.

The vision. Give an agent a job the way you'd give a person one: a desk, the keys that job needs, someone who signs off on what matters, and a record of what they did. It earns more as it proves itself.

Five principles

1. Keys, not rules. An agent can do only what its credentials allow. A payment belongs to the one agent that holds the payment key, and every other agent has to ask it. A rule can be talked around, but a missing key can't.
2. Limits live outside the agent. Inside its own workspace an agent is a power user: it installs packages and runs code. The in-container hooks catch accidents. The boundary that holds sits in the platform: the credentials it was granted, the platform calls it may make, and the settings only a person can change. Prompts shape behaviour; they never set bounds.
3. Sign-off before the work, never during. You mark an action on an agent as "needs a yes from ". The request goes to the person in that role before the agent starts. Nothing pauses halfway and resumes on stale state. The asking agent never approves its own request, and silence is never consent.
4. Trust is earned per kind of work. A new agent starts on a short leash. A kind of task graduates from "on request" to "just do it" on evidence, and drops back after a bad call. Earned trust changes when an agent acts, never what it may touch. Only a person removes a gate.
5. Everything leaves a receipt. Grants, refusals and approvals are recorded, in a hash-chained audit log, along with which key acted. You can always answer who allowed this, who did it, and how to stop it.

What it feels like

• An operator opens one agent and sees what it can touch, what needs a yes, and what it did. One click stops it, revokes its credentials, or switches it to read-only.
• An approver gets one card: "Pay Acme $4,200, requested by the ops agent." She approves. The finance agent pays, and the ops agent is told.
• An agent that reaches for something it wasn't given is told plainly what is missing, and it asks.

What we deliberately don't do

• Sell prompt-based guardrails as safety.
• Block individual functions inside an agent. It routes around them.
• Turn agents back into scripts to make them safe.
• Put a human on every step. That isn't delegation.

Where it stands

A table with four rows (Hold · Sign-off · Trust · See & stop) and three columns (Available now · Next release · Planned), filled from code truth per the acceptance criteria. Planned items include outbound network allow-lists, per-agent spend caps, approvals bound to the exact effect (amount, payee), and one control page per agent.

Honest limits

• Guardrails are strongest on the Claude Code runtime. Say per runtime what holds.
• Agents can reach the open internet today.
• An agent holding a raw credential and a shell can act outside its skills. That is why "one key, one agent" is the boundary we rely on.