polyc_capability/

lib.rs

//! Capability taxonomy, derivation functions, and the pure gate decision
//! engine (`#587`, `#591`).
//!
//! One tool call *requires* a set of [`Capability`]s (derived from its spec's
//! MCP-style annotations plus its registry provenance) and is *granted* a set
//! (derived from the agent's policy plus the conversation's provenance/taint
//! state at that moment). [`decide`] compares them and returns the single
//! [`GateOutcome`] for the call — the one decision path that replaces the
//! previous OR of an argument-aware policy check, a sandbox-denial escalation,
//! and a runtime "untrusted content + egress" override.
//!
//! The containment invariants live here as pure logic, testable exhaustively:
//!
//! - Untrusted content in context removes [`Capability::ArbitraryEgress`]
//!   **and** [`Capability::MutateExternal`] from the granted set — a message
//!   body or an issue title carries attacker-steered bytes out as surely as a
//!   fetch does.
//! - A tool whose spec cannot be classified requires the full privileged set
//!   ([`CapabilitySet::all`]) — fail closed.
//! - The model is monotonic: under a fixed policy, adding taint never adds a
//!   capability.
//!
//! Everything here is a pure function over its inputs. No gate wiring, no IO,
//! no clock: the executor surface (`#592`) derives the inputs and the agent's
//! per-call gate (`#593`) is a thin adapter over [`decide`].

use polyc_llm::ToolSpec;

// ── Capability + set ─────────────────────────────────────────────────────────

/// One thing a tool call can do — the unit of the containment model.
///
/// The taxonomy is deliberately small and rarely changes. Adding a member
/// means extending this enum and the two derivation functions
/// ([`required_capabilities`], [`granted_capabilities`]); the decision engine
/// ([`decide`]) operates on sets generically and never needs to change (a
/// pinned test demonstrates this).
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[repr(u16)]
pub enum Capability {
    /// Read state confined to the conversation's sandbox (workspace files).
    LocalRead = 1,
    /// Mutate state confined to the conversation's sandbox (workspace writes,
    /// sandboxed shell). Destructive *inside the box* is still local.
    LocalWrite = 1 << 1,
    /// Call an operator-registered connector endpoint (or a first-party
    /// control-plane service) — a fixed destination the operator vouched for,
    /// carrying only model-authored arguments. Taint never revokes this.
    FixedConnectorRead = 1 << 2,
    /// Send bytes to a model-controlled external destination — the built-in
    /// web/paid fetchers. The classic exfiltration channel.
    ArbitraryEgress = 1 << 3,
    /// Perform a side effect outside the sandbox: mutate external state,
    /// send a message, file an issue, spend money. An external mutation
    /// carries model-authored bytes to destinations an attacker may read,
    /// so it is an egress channel in effect even when the destination is
    /// fixed.
    MutateExternal = 1 << 4,
    /// Grant a third party access to the system itself — the admin invite
    /// (`#700`). Deliberately held OUT of [`Self::ALL`], so
    /// it is never in [`CapabilitySet::all`], never in the default grant, and —
    /// because [`Self::from_name`] only recognizes members of [`Self::ALL`] —
    /// unnameable in operator config: no policy or wire input can ever seed it
    /// into a granted set. A tool that requires it therefore always exceeds its
    /// granted set and always escalates to a human, in every taint state and
    /// policy mode. This is the structural mechanism behind "an access-grant is
    /// never autonomous — a person always confirms the exact invitee".
    GrantAccess = 1 << 5,
    /// Remove a third party's access to the system itself — the admin
    /// de-admission (`#713`), the offboarding sibling of [`Self::GrantAccess`].
    /// Held OUT of [`Self::ALL`] for the identical reason: never in
    /// [`CapabilitySet::all`], never in the default grant, and unnameable in
    /// operator config ([`Self::from_name`] only recognizes [`Self::ALL`]
    /// members), so a tool requiring it always exceeds its granted set and
    /// always escalates to a human, in every taint state and policy mode. This
    /// is the structural mechanism behind "a removal is never autonomous — a
    /// person always confirms the exact person being removed".
    RevokeAccess = 1 << 6,
    /// Take away a persona's ADMIN ROLE — the `demote` tool (`#715`), and the
    /// sibling that completes the admin-management set alongside
    /// [`Self::GrantAccess`]/[`Self::RevokeAccess`]. Held OUT of [`Self::ALL`]
    /// for the identical reason: never in [`CapabilitySet::all`], never in the
    /// default grant, and unnameable in operator config ([`Self::from_name`]
    /// only recognizes [`Self::ALL`] members), so a tool requiring it always
    /// exceeds its granted set and always escalates to a human, in every
    /// taint state and policy mode. This is the structural mechanism behind
    /// "an admin's role is never removed autonomously — a person always
    /// confirms exactly whose role is being taken away".
    ///
    /// This used to occupy the last bit `u8` could hold (`1 << 7`); adding
    /// [`Self::GrantAdmin`] widened `CapabilitySet` (and this enum's
    /// `#[repr]`) from `u8` to `u16`, so a further marker needs no more
    /// widening — `u16` has eight bits to spare.
    ManageAdmin = 1 << 7,
    /// Make a persona an ADMIN — the `promote` tool (POLY-223), the
    /// admission-granting sibling of [`Self::ManageAdmin`] that completes the
    /// admin-management set alongside [`Self::GrantAccess`]/
    /// [`Self::RevokeAccess`]. Held OUT of [`Self::ALL`] for the identical
    /// reason: never in [`CapabilitySet::all`], never in the default grant,
    /// and unnameable in operator config ([`Self::from_name`] only
    /// recognizes [`Self::ALL`] members), so a tool requiring it always
    /// exceeds its granted set and always escalates to a human, in every
    /// taint state and policy mode. This is the structural mechanism behind
    /// "an admin role is never granted autonomously — a person always
    /// confirms exactly who is being made an admin."
    ///
    /// Deliberately its OWN marker rather than a reuse of
    /// [`Self::ManageAdmin`]: the escalation copy the gate renders is
    /// directional (see [`escalation_reason`]) — reusing `ManageAdmin` would
    /// make a PROMOTION's approval card read "would take away someone's
    /// admin role," the opposite of what is actually being authorized.
    GrantAdmin = 1 << 8,
}

impl Capability {
    /// Every *grantable* member of the taxonomy, in declaration order.
    ///
    /// [`Self::GrantAccess`] and [`Self::RevokeAccess`] are deliberately
    /// absent: they are the never-granted markers (see their docs), so they
    /// are excluded from [`CapabilitySet::all`], the default grant, name
    /// parsing ([`Self::from_name`]), and set iteration — everything driven
    /// off this array operates only over the grantable set.
    pub const ALL: [Self; 5] = [
        Self::LocalRead,
        Self::LocalWrite,
        Self::FixedConnectorRead,
        Self::ArbitraryEgress,
        Self::MutateExternal,
    ];

    /// Stable kebab-case name, used in signed approval coverage and telemetry.
    /// Inverse of [`Self::from_name`].
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::LocalRead => "local-read",
            Self::LocalWrite => "local-write",
            Self::FixedConnectorRead => "fixed-connector-read",
            Self::ArbitraryEgress => "arbitrary-egress",
            Self::MutateExternal => "mutate-external",
            Self::GrantAccess => "grant-access",
            Self::RevokeAccess => "revoke-access",
            Self::ManageAdmin => "manage-admin",
            Self::GrantAdmin => "grant-admin",
        }
    }

    /// Parse a stable kebab-case name; `None` for anything unrecognized so a
    /// caller reading operator config fails toward granting nothing.
    #[must_use]
    pub fn from_name(name: &str) -> Option<Self> {
        Self::ALL.into_iter().find(|c| c.as_str() == name)
    }
}

/// A set of [`Capability`]s. Small, `Copy`, and closed under the usual set
/// algebra — the decision engine works only through these operations.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Hash)]
pub struct CapabilitySet(u16);

/// Scoping/audit name for the LLM provider's native web-search-grounding
/// primitive (issue `#1226`).
///
/// A request-level flag the provider turns into its own built-in search tool
/// entry mid-generation, never a model-invoked `tool_use` call. Lives here
/// (rather than `polyc_tools`, where every other tool name lives) because
/// both `polyc_agent` (the per-step gate that consults it) and `polyc_tools`
/// (the `builtinTools` scoping check) need the same literal and neither crate
/// may depend on the other.
pub const NATIVE_SEARCH_GROUNDING: &str = "web_search_grounding";

impl CapabilitySet {
    /// The empty set.
    pub const EMPTY: Self = Self(0);

    /// The capabilities the provider's native web-search-grounding primitive
    /// ([`NATIVE_SEARCH_GROUNDING`]) requires.
    ///
    /// The classic exfiltration channel, the same floor as the built-in web
    /// fetchers (`web_fetch`, `paid_fetch`). Unlike every other tool, this
    /// primitive is never a [`polyc_llm::ToolSpec`] the model calls
    /// explicitly, so there is no per-call `tool_use` for the ordinary
    /// classification path (`required_capabilities`) to inspect — the call
    /// site that decides whether to turn grounding on for a step compares
    /// this constant against [`granted_capabilities`] directly, via the same
    /// [`decide`] every real tool call goes through.
    #[must_use]
    pub const fn native_search_grounding_requirements() -> Self {
        Self::of(Capability::ArbitraryEgress)
    }

    /// The full privileged set — every member of the taxonomy. This is the
    /// fail-closed requirement for an unclassifiable tool.
    #[must_use]
    pub const fn all() -> Self {
        let mut bits = 0u16;
        let mut i = 0;
        while i < Capability::ALL.len() {
            bits |= Capability::ALL[i] as u16;
            i += 1;
        }
        Self(bits)
    }

    /// The set containing exactly `capability`.
    #[must_use]
    pub const fn of(capability: Capability) -> Self {
        Self(capability as u16)
    }

    /// This set plus `capability`.
    #[must_use]
    pub const fn with(self, capability: Capability) -> Self {
        Self(self.0 | capability as u16)
    }

    /// Whether `capability` is in this set.
    #[must_use]
    pub const fn contains(self, capability: Capability) -> bool {
        self.0 & capability as u16 != 0
    }

    /// Whether this set has no members.
    #[must_use]
    pub const fn is_empty(self) -> bool {
        self.0 == 0
    }

    /// Whether every member of this set is also in `other`.
    #[must_use]
    pub const fn is_subset_of(self, other: Self) -> bool {
        self.0 & !other.0 == 0
    }

    /// Set union.
    #[must_use]
    pub const fn union(self, other: Self) -> Self {
        Self(self.0 | other.0)
    }

    /// Set intersection.
    #[must_use]
    pub const fn intersection(self, other: Self) -> Self {
        Self(self.0 & other.0)
    }

    /// Set difference: the members of this set that are not in `other`.
    #[must_use]
    pub const fn difference(self, other: Self) -> Self {
        Self(self.0 & !other.0)
    }

    /// The members of this set, in [`Capability::ALL`] order.
    pub fn iter(self) -> impl Iterator<Item = Capability> {
        Capability::ALL
            .into_iter()
            .filter(move |c| self.contains(*c))
    }

    /// Build a set from stable kebab-case names, such as signed approval
    /// coverage. Unrecognized names are NOT granted — they are returned
    /// separately so the caller can
    /// log them — which is the fail-closed direction: a typo in operator
    /// config grants nothing rather than something unintended.
    pub fn from_names<'a, I: IntoIterator<Item = &'a str>>(names: I) -> (Self, Vec<String>) {
        let mut set = Self::EMPTY;
        let mut unknown = Vec::new();
        for name in names {
            match Capability::from_name(name) {
                Some(c) => set = set.with(c),
                None => unknown.push(name.to_owned()),
            }
        }
        (set, unknown)
    }

    /// The stable kebab-case names of this set's members, in
    /// [`Capability::ALL`] order — the inverse of [`Self::from_names`].
    #[must_use]
    pub fn names(self) -> Vec<&'static str> {
        self.iter().map(Capability::as_str).collect()
    }
}

impl FromIterator<Capability> for CapabilitySet {
    fn from_iter<I: IntoIterator<Item = Capability>>(iter: I) -> Self {
        iter.into_iter().fold(Self::EMPTY, Self::with)
    }
}

/// The capabilities that untrusted content in context revokes: both channels
/// that carry model-authored bytes to destinations an attacker may read.
///
/// This is the single, tested home of the containment rule that used to be
/// the "lethal trifecta override": [`Capability::ArbitraryEgress`] (a fetch to
/// a model-chosen destination) **and** [`Capability::MutateExternal`] (a
/// message body or issue field is an exfiltration channel the egress rule
/// alone would miss).
pub const TAINT_REVOKED: CapabilitySet =
    CapabilitySet::of(Capability::ArbitraryEgress).with(Capability::MutateExternal);

// ── Requirement derivation ────────────────────────────────────────────────────

/// Where a tool comes from — the registry-provenance half of classification.
///
/// Trust scoping is the security-load-bearing part: taint-immune
/// classification ([`Capability::FixedConnectorRead`]) is earned only by
/// operator registration ([`ToolOrigin::RegisteredConnector`] /
/// [`ToolOrigin::FirstParty`]) — never by a connector's self-declared
/// annotation hints alone. This is what the MCP specification normatively
/// requires: clients MUST treat tool annotations as untrusted unless the
/// server is trusted.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ToolOrigin {
    /// A process-local built-in, such as a coding tool. This origin describes
    /// local file authority. It does not prove operating-system network
    /// isolation. `shell_exec` can use routes allowed by the pod policy today;
    /// issue `#2508` owns alignment with this taxonomy and D6's route-removal
    /// checklist.
    LocalSandbox,
    /// A built-in fetcher (the web/paid fetchers): brokered on the trusted
    /// side to a model-controlled destination.
    Fetcher,
    /// A built-in that reads or acts on the caller's own first-party state via
    /// the control plane (the history and wallet families): a fixed,
    /// operator-owned destination.
    FirstParty,
    /// A built-in that grants a third party access to the system itself — the
    /// admin invite (`#700`). Classified apart from [`Self::FirstParty`]
    /// because it requires [`Capability::GrantAccess`], the never-granted
    /// marker, so it always escalates to a human before anything is minted: the
    /// agent can only ever PROPOSE an invite, never grant access on its own.
    AccessGrant,
    /// A built-in that removes a third party's access to the system itself —
    /// the admin de-admission (`#713`), the offboarding sibling of
    /// [`Self::AccessGrant`]. Requires [`Capability::RevokeAccess`], the
    /// never-granted marker, so it always escalates to a human before anything
    /// is removed: the agent can only ever PROPOSE a removal, never de-admit
    /// anyone on its own.
    AccessRevoke,
    /// A built-in that takes away a persona's ADMIN ROLE — the `demote`
    /// tool (`#715`), the sibling that completes the admin-management set
    /// alongside [`Self::AccessGrant`]/[`Self::AccessRevoke`]. Requires
    /// [`Capability::ManageAdmin`], the never-granted marker, so it always
    /// escalates to a human before anyone's admin role changes: the agent
    /// can only ever PROPOSE a demote, never remove anyone's admin role on
    /// its own.
    AdminManage,
    /// A built-in that makes a persona an ADMIN — the `promote` tool
    /// (POLY-223), the admission-granting sibling that completes the
    /// admin-management set alongside [`Self::AccessGrant`]/
    /// [`Self::AccessRevoke`]/[`Self::AdminManage`]. Requires
    /// [`Capability::GrantAdmin`], the never-granted marker, so it always
    /// escalates to a human before anyone's admin role changes: the agent
    /// can only ever PROPOSE a promotion, never grant the admin role on its
    /// own.
    ///
    /// Classified apart from [`Self::AdminManage`] rather than sharing its
    /// capability marker: [`escalation_reason`]'s copy for that marker is
    /// directional ("would take away someone's admin role"), which would
    /// misdescribe a promotion's approval card, so the grant direction earns
    /// its own marker and its own wording.
    AdminGrant,
    /// A connector tool whose server the operator registered (registry
    /// provenance, e.g. the `ToolService` registry). Its annotations are
    /// load-bearing inputs because the operator vouched for the server.
    RegisteredConnector,
    /// Anything else: an unregistered server's self-declared tool, an unknown
    /// name, an unannotated spec. Fails closed to the privileged set.
    Unknown,
}

/// The classification inputs for one tool: its spec's MCP-style annotations
/// plus its registry provenance.
///
/// Built by the executor surface (`#592`) — [`ToolProfile::for_spec`] reads
/// the annotations off the spec, and the executor supplies the origin from
/// what it knows about the tool's source.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ToolProfile {
    /// Registry provenance — see [`ToolOrigin`].
    pub origin: ToolOrigin,
    /// MCP `readOnlyHint`: the tool does not modify its environment.
    pub read_only: bool,
    /// MCP `destructiveHint`: the tool may perform irreversible or
    /// side-effecting changes.
    pub destructive: bool,
    /// MCP `openWorldHint`: the tool's RESULT may carry content of
    /// uncontrolled provenance. An ingestion-source property: it drives
    /// taint, not the required set (a registered connector's open-world read
    /// still dials only its fixed, operator-vouched endpoint).
    pub open_world: bool,
}

impl ToolProfile {
    /// Read the classification annotations off `spec`, with the
    /// executor-supplied registry provenance.
    #[must_use]
    pub const fn for_spec(spec: &ToolSpec, origin: ToolOrigin) -> Self {
        Self {
            origin,
            read_only: spec.read_only,
            destructive: spec.destructive,
            open_world: spec.open_world,
        }
    }
}

/// Derive the capabilities a tool call requires from its profile — the
/// spec's existing annotations plus registry provenance. No new hand-written
/// per-tool metadata.
///
/// The mapping (see the `#587` design):
///
/// - sandbox-confined built-in ⇒ local read (+ local write unless read-only —
///   destructive *inside the box* is still local);
/// - built-in fetcher ⇒ arbitrary egress (+ external mutation when
///   destructive, e.g. a paying fetch);
/// - first-party / operator-registered connector ⇒ fixed-connector read
///   (+ external mutation unless read-only and non-destructive);
/// - access-grant (the admin invite) ⇒ the never-granted
///   [`Capability::GrantAccess`], so it always escalates to a human;
/// - unknown / unclassifiable ⇒ the full privileged set, fail closed: an
///   unknown tool never slips through un-gated.
///
/// `open_world` is deliberately not consulted: it marks an ingestion source
/// (drives taint when the result enters context), not an outbound
/// capability.
#[must_use]
pub const fn required_capabilities(profile: ToolProfile) -> CapabilitySet {
    match profile.origin {
        ToolOrigin::LocalSandbox => {
            if profile.read_only {
                CapabilitySet::of(Capability::LocalRead)
            } else {
                CapabilitySet::of(Capability::LocalRead).with(Capability::LocalWrite)
            }
        }
        ToolOrigin::Fetcher => {
            if profile.destructive {
                CapabilitySet::of(Capability::ArbitraryEgress).with(Capability::MutateExternal)
            } else {
                CapabilitySet::of(Capability::ArbitraryEgress)
            }
        }
        ToolOrigin::FirstParty | ToolOrigin::RegisteredConnector => {
            if profile.read_only && !profile.destructive {
                CapabilitySet::of(Capability::FixedConnectorRead)
            } else {
                CapabilitySet::of(Capability::FixedConnectorRead).with(Capability::MutateExternal)
            }
        }
        // The admin invite: it requires only the never-granted
        // `GrantAccess`, so the gate escalates it in EVERY taint state and
        // policy mode. The annotations are not consulted — proposing an
        // access-grant always needs a person, regardless of how the tool
        // declares itself. The actual mint's first-party mutation is enforced
        // control-plane-side, after approval, not modeled as the agent call's
        // granted capability.
        ToolOrigin::AccessGrant => CapabilitySet::of(Capability::GrantAccess),
        // The admin de-admission (#713): the offboarding sibling of the admin
        // invite above — same reasoning, same never-granted-marker mechanism.
        ToolOrigin::AccessRevoke => CapabilitySet::of(Capability::RevokeAccess),
        // The admin demote (#715): completes the admin-management set —
        // same reasoning, same never-granted-marker mechanism.
        ToolOrigin::AdminManage => CapabilitySet::of(Capability::ManageAdmin),
        // The admin promote (POLY-223): the admission-granting sibling of
        // the demote arm above — same reasoning, same never-granted-marker
        // mechanism, its own marker so the escalation copy stays directional.
        ToolOrigin::AdminGrant => CapabilitySet::of(Capability::GrantAdmin),
        ToolOrigin::Unknown => CapabilitySet::all(),
    }
}

/// Clamp a re-declared profile so a connector's runtime annotation change can
/// only ever ADD required capabilities (`#598`).
///
/// A connector may re-declare its tools mid-conversation (list-changed). A
/// re-declaration never removes a requirement and never earns taint-immunity
/// at runtime: the merged profile keeps the *less* trusted value of each
/// annotation (loses `read_only` if either side lost it, keeps `destructive`
/// and `open_world` if either side had it). The origin is NOT an input from
/// the re-declaration at all — registry provenance is an operator act the
/// executor derives, never something a connector can assert about itself —
/// so the merged profile keeps the origin the conversation started with.
/// The result is pinned monotonic by test:
/// `required_capabilities(monotonic_redeclaration(old, new))` is always a
/// superset of `required_capabilities(old)`.
#[must_use]
pub const fn monotonic_redeclaration(old: ToolProfile, new: ToolProfile) -> ToolProfile {
    ToolProfile {
        origin: old.origin,
        read_only: old.read_only && new.read_only,
        destructive: old.destructive || new.destructive,
        open_world: old.open_world || new.open_world,
    }
}

// ── Deployment viability (#1415) ────────────────────────────────────────────────

/// A browser-facing ceremony page a built-in mints a one-time link to.
///
/// Closed and small on purpose: only ceremonies that actually gate a
/// chat-callable built-in belong here. `wallet-passkey-login` (the web app's
/// own sign-in) is a real deployment ceremony too, but it backs no built-in
/// tool call — it is a pure browser flow a person reaches directly, never
/// something the model mints a link to — so adding it here would leave a
/// [`Requirement`] variant no built-in ever resolves to, which the harness's
/// dead-variant guard exists to catch.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Ceremony {
    /// The wallet-link card (`POLYCHROME_WALLET_LINK_URL`): mints the link a
    /// caller signs to attach an external wallet, and the shared page the
    /// spending-limit-update and hard-revoke ceremonies reuse.
    WalletLink,
    /// The email-verification magic-link page (`POLYCHROME_EMAIL_LINK_URL`):
    /// mints the link a caller clicks to verify an email address.
    EmailMagicLink,
}

/// A deployment prerequisite a built-in's calls depend on.
///
/// A closed, exhaustively matchable taxonomy of the STATIC, versioned facts a
/// built-in family needs configured before any call of its own can do
/// anything, sibling to [`ToolOrigin`] in the same "static shape of the
/// built-in surface" sense. Carries only the fact, never remedy text: the
/// copy a person reads about a missing prerequisite belongs to the surface
/// that renders it (an approval card, a status tool), not to this taxonomy.
///
/// Extending the taxonomy means adding a variant here and teaching
/// `polyc_tools::capability::builtin_requirements` (`crates/tools`) which
/// built-ins need it, and [`DeploymentCapabilities::is_viable`] which
/// deployment fact answers it — the harness's `builtin_surface_guard` fails
/// closed if either side is left out (a requirement no built-in resolves to,
/// or a built-in a requirement can't classify).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Requirement {
    /// A usable outbound mail relay (credentials/token valid, not merely a
    /// relay URL set — a missing URL alone falls back to a hosted default).
    /// `link_email` needs this to actually deliver a verification message.
    MailRelay,
    /// A configured browser-facing ceremony page — see [`Ceremony`].
    CeremonyPage(Ceremony),
    /// The outbound-payments proxy: a settlement currency and a way to sign
    /// (a deployment env signer or a caller's own delegated wallet key).
    /// `paid_fetch` needs this to ever send a payment.
    PaymentsProxy,
}

impl Requirement {
    /// Every concrete [`Requirement`] value, in declaration order — the
    /// enumeration [`DeploymentCapabilities::viable_names`] and
    /// [`Self::from_name`] iterate over, and the harness guard's
    /// dead-variant check walks.
    pub const ALL: [Self; 4] = [
        Self::MailRelay,
        Self::CeremonyPage(Ceremony::WalletLink),
        Self::CeremonyPage(Ceremony::EmailMagicLink),
        Self::PaymentsProxy,
    ];

    /// Stable kebab-case name, used on the wire
    /// (`TurnInput.viable_requirements`) and as a telemetry label. Inverse of
    /// [`Self::from_name`].
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::MailRelay => "mail-relay",
            Self::CeremonyPage(Ceremony::WalletLink) => "ceremony-page:wallet-link",
            Self::CeremonyPage(Ceremony::EmailMagicLink) => "ceremony-page:email-magic-link",
            Self::PaymentsProxy => "payments-proxy",
        }
    }

    /// Parse a stable kebab-case name; `None` for anything unrecognized so a
    /// caller reading the wire fails toward treating the requirement as
    /// unmet rather than guessing.
    #[must_use]
    pub fn from_name(name: &str) -> Option<Self> {
        Self::ALL.into_iter().find(|r| r.as_str() == name)
    }
}

/// The deployment-configuration facts [`Requirement`]s are checked against.
///
/// Resolved ONCE at control-plane startup from the same `Option`/`Arc`
/// configuration each ceremony/proxy already builds for its own use (never a
/// second, independent env read that could drift from what the ceremony
/// itself decided), mirroring `ConfiguredBackends` in the harness's
/// `main.rs`: a struct of independent configuration facts, not states of one
/// state machine — hence the flat bools below rather than a nested
/// enum/state-machine shape.
///
/// Carried across the control-plane/harness wire as
/// `TurnInput.viable_requirements` (the [`Requirement::as_str`] names this
/// deployment satisfies) because the facts live in control-plane-only
/// configuration (mail relay credentials, ceremony URLs, the payments
/// signer) the harness sandbox cannot read for itself — the harness never
/// resolves this struct locally; it reconstructs the viable subset with
/// [`Self::from_names`] from the wire strings each turn.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
#[allow(clippy::struct_excessive_bools)] // four INDEPENDENT config facts (see doc above), not a state machine
pub struct DeploymentCapabilities {
    /// [`Requirement::MailRelay`] is met.
    pub mail_relay: bool,
    /// <code>[Requirement::CeremonyPage]([Ceremony::WalletLink])</code> is met.
    pub wallet_link_ceremony: bool,
    /// <code>[Requirement::CeremonyPage]([Ceremony::EmailMagicLink])</code> is met.
    pub email_magic_link_ceremony: bool,
    /// [`Requirement::PaymentsProxy`] is met.
    pub payments_proxy: bool,
}

impl DeploymentCapabilities {
    /// Every [`Requirement`] viable — the standalone/dev/test posture, and
    /// the explicit choice a caller that genuinely does not care about
    /// deployment viability (a test scoping only `builtin_allow`, the
    /// in-process whole-conversation test transport) reaches for by name
    /// instead of hand-listing every field `true`. NOT the type's
    /// [`Default`] — [`Default`] stays fail-closed (nothing viable), so a
    /// caller that forgets to thread the real wire-resolved value hides
    /// every requirement-gated built-in instead of silently over-advertising
    /// one whose deployment prerequisite is actually unmet.
    #[must_use]
    pub const fn all() -> Self {
        Self {
            mail_relay: true,
            wallet_link_ceremony: true,
            email_magic_link_ceremony: true,
            payments_proxy: true,
        }
    }

    /// Whether this deployment currently satisfies `requirement`.
    #[must_use]
    pub const fn is_viable(self, requirement: Requirement) -> bool {
        match requirement {
            Requirement::MailRelay => self.mail_relay,
            Requirement::CeremonyPage(Ceremony::WalletLink) => self.wallet_link_ceremony,
            Requirement::CeremonyPage(Ceremony::EmailMagicLink) => self.email_magic_link_ceremony,
            Requirement::PaymentsProxy => self.payments_proxy,
        }
    }

    /// Whether every member of `requirements` is viable — the join
    /// `build_tool_executor` folds into `granted ∩ owned ∩ viable`. An empty
    /// slice (a built-in with no deployment prerequisite) is always viable.
    #[must_use]
    pub fn all_viable(self, requirements: &[Requirement]) -> bool {
        requirements.iter().all(|r| self.is_viable(*r))
    }

    /// The stable kebab-case names of every [`Requirement`] this deployment
    /// satisfies, in [`Requirement::ALL`] order — what the control plane
    /// puts on the wire. Inverse of [`Self::from_names`].
    #[must_use]
    pub fn viable_names(self) -> Vec<&'static str> {
        Requirement::ALL
            .into_iter()
            .filter(|r| self.is_viable(*r))
            .map(Requirement::as_str)
            .collect()
    }

    /// Reconstruct from the wire's stable-name list (`TurnInput.viable_requirements`)
    /// — the harness's side of [`Self::viable_names`]. An unrecognized name
    /// (a newer control plane's requirement an older harness doesn't know)
    /// is silently ignored rather than failing the turn: an unknown
    /// requirement can never be satisfied by an older binary's `is_viable`
    /// match anyway, so any built-in that needs it stays hidden either way.
    #[must_use]
    pub fn from_names<'a, I: IntoIterator<Item = &'a str>>(names: I) -> Self {
        let mut caps = Self::default();
        for name in names {
            match Requirement::from_name(name) {
                Some(Requirement::MailRelay) => caps.mail_relay = true,
                Some(Requirement::CeremonyPage(Ceremony::WalletLink)) => {
                    caps.wallet_link_ceremony = true;
                }
                Some(Requirement::CeremonyPage(Ceremony::EmailMagicLink)) => {
                    caps.email_magic_link_ceremony = true;
                }
                Some(Requirement::PaymentsProxy) => caps.payments_proxy = true,
                None => {}
            }
        }
        caps
    }
}

// ── Grant derivation ──────────────────────────────────────────────────────────

/// Whether untrusted content is in the conversation's context at this gate
/// decision.
///
/// The provenance (taint) input to grant derivation, computed from the
/// durable seed OR the live transcript scan, never from the turn's own
/// output.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum TaintState {
    /// No untrusted content in context.
    #[default]
    Clean,
    /// Untrusted content is in context: the granted set loses
    /// [`TAINT_REVOKED`].
    Tainted,
}

/// The agent's configured capability policy — the operator-controlled half of
/// grant derivation.
///
/// The policy comes from cluster config (the Agent custom resource),
/// unreachable from within a conversation or the request path.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct GrantPolicy {
    /// The capabilities the agent's policy grants on a clean context.
    pub base: CapabilitySet,
}

impl Default for GrantPolicy {
    /// Grant everything on a clean context.
    fn default() -> Self {
        Self {
            base: CapabilitySet::all(),
        }
    }
}

/// Derive the capabilities granted to one gate decision from the agent's
/// policy and the provenance state **at that moment**.
///
/// Recomputed per call, because taint can enter mid-turn and must revoke for
/// the very next call.
///
/// The containment rule: taint present ⇒ [`TAINT_REVOKED`] (arbitrary egress
/// AND external mutation) removed from the granted set. Monotonic under a fixed
/// policy: adding taint never adds a capability (pinned by test).
#[must_use]
pub const fn granted_capabilities(policy: GrantPolicy, taint: TaintState) -> CapabilitySet {
    match taint {
        TaintState::Clean => policy.base,
        TaintState::Tainted => policy.base.difference(TAINT_REVOKED),
    }
}

// ── Decision engine ───────────────────────────────────────────────────────────

/// An argument transform the argument-aware dispatch policy asked for, honored
/// only when the call is otherwise allowed.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub enum ArgTransform {
    /// Run the call as proposed.
    #[default]
    None,
    /// Run the call with these replacement arguments.
    Rewrite(String),
    /// Prepend this context as an internal-only note before the call runs.
    InjectContext(String),
}

/// The per-call policy verdicts [`decide`] folds into the one outcome.
///
/// Carries the argument-aware dispatch decision plus the sandbox-escalation
/// check, already evaluated against the call's arguments by the caller.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct CallPolicy {
    /// A hard policy veto with its reason: the call is blocked without a
    /// human prompt and a human approval cannot satisfy it. Takes precedence
    /// over everything else.
    pub veto: Option<String>,
    /// The argument-aware policy (or the tool's intrinsic gate) demands a
    /// human decision for this call regardless of capabilities.
    pub requires_human: bool,
    /// The sandbox would deny this call before any side effect and the
    /// deployment escalates such denials to a human instead of running into
    /// the flat denial.
    pub sandbox_escalation: bool,
    /// The argument transform to honor when the call is allowed.
    pub transform: ArgTransform,
}

/// The single unified gate result for one tool call — replaces both the
/// argument-aware `ToolDecision` and the `needs_approval`/override booleans.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum GateOutcome {
    /// Execute the call as proposed.
    Allow,
    /// Execute the call with rewritten arguments.
    Modify(
        /// The replacement arguments (JSON).
        String,
    ),
    /// Prepend this context as an internal-only note, then execute.
    InjectContext(
        /// The note text.
        String,
    ),
    /// Pause for a human decision.
    Escalate {
        /// Why, in plain language for the approval card. Empty for an
        /// ordinary policy/sandbox gate (the edge renders its default
        /// prompt); non-empty when capabilities are missing.
        reason: String,
        /// The required capabilities the call's granted set does not cover.
        /// Empty when the escalation is a policy/sandbox gate rather than a
        /// capability shortfall.
        missing: CapabilitySet,
    },
    /// Block the call without a human prompt; the reason is surfaced to the
    /// model as the tool result so it can adapt.
    Deny(
        /// The policy's reason.
        String,
    ),
}

impl GateOutcome {
    /// Stable lowercase label for telemetry — one counter per gate outcome.
    #[must_use]
    pub const fn label(&self) -> &'static str {
        match self {
            Self::Allow => "allow",
            Self::Modify(_) => "modify",
            Self::InjectContext(_) => "inject_context",
            Self::Escalate { .. } => "escalate",
            Self::Deny(_) => "deny",
        }
    }
}

/// The one pure decision: compare what the call requires with what it is
/// granted, under the argument-aware policy verdicts, and return the single
/// [`GateOutcome`].
///
/// Precedence, pinned by test:
///
/// 1. hard policy veto ⇒ [`GateOutcome::Deny`];
/// 2. required ⊄ granted ⇒ [`GateOutcome::Escalate`] carrying the missing
///    set and a plain-language reason;
/// 3. the policy demands a human (argument-aware gate or sandbox-denial
///    escalation) ⇒ [`GateOutcome::Escalate`] with an empty missing set;
/// 4. otherwise honor the argument transform or allow.
///
/// The engine is pure set algebra over the capability sets — it never
/// matches on a specific [`Capability`], so extending the taxonomy requires
/// no change here (pinned by test).
#[must_use]
pub fn decide(
    required: CapabilitySet,
    granted: CapabilitySet,
    policy: &CallPolicy,
    tool_name: &str,
) -> GateOutcome {
    if let Some(reason) = &policy.veto {
        return GateOutcome::Deny(reason.clone());
    }
    let missing = required.difference(granted);
    if !missing.is_empty() {
        return GateOutcome::Escalate {
            reason: escalation_reason(tool_name, missing),
            missing,
        };
    }
    if policy.requires_human || policy.sandbox_escalation {
        return GateOutcome::Escalate {
            reason: String::new(),
            missing: CapabilitySet::EMPTY,
        };
    }
    match &policy.transform {
        ArgTransform::None => GateOutcome::Allow,
        ArgTransform::Rewrite(args) => GateOutcome::Modify(args.clone()),
        ArgTransform::InjectContext(note) => GateOutcome::InjectContext(note.clone()),
    }
}

/// The plain-language reason for a missing-capability escalation, rendered
/// verbatim on the approval card on every edge (one shared helper so the
/// wording never differs by surface).
///
/// User-facing copy: no internal terms, active sentences, honest about risk
/// without overclaiming. In the current model a capability is only ever
/// missing because untrusted content entered the conversation (the base
/// policy grants everything), so the copy names that cause; a future
/// narrowed base policy reuses the same wording — the access is missing
/// either way, and the approver's decision is the same.
///
/// The `MutateExternal`-missing arms in particular name a possibility being
/// checked, not a fact about the call: the gate has no way to confirm a call
/// is read-only here (an unannotated registered tool, or any unregistered
/// tool falling back to [`CapabilitySet::all`], lands on this arm whether or
/// not it ever changes anything), so the copy says the check runs before the
/// tool "could" reach out or mutate, never that it will.
#[must_use]
pub fn escalation_reason(tool_name: &str, missing: CapabilitySet) -> String {
    // The access-grant marker takes precedence: an invite always needs a person
    // to confirm the exact invitee, in every conversation state, so the wording
    // is about the grant itself, not about any content the conversation took in.
    if missing.contains(Capability::GrantAccess) {
        return format!(
            "`{tool_name}` would give someone access to Polychrome, so a person needs to \
             confirm exactly who's being invited before it goes ahead"
        );
    }
    // The revoke-access marker takes the same precedence, for the same reason:
    // removing someone's access always needs a person to confirm exactly who,
    // in every conversation state.
    if missing.contains(Capability::RevokeAccess) {
        return format!(
            "`{tool_name}` would remove someone's access to Polychrome, so a person needs to \
             confirm exactly who's being removed before it goes ahead"
        );
    }
    // The grant-admin marker takes the same precedence: making someone an
    // admin always needs a person to confirm exactly who, in every
    // conversation state.
    if missing.contains(Capability::GrantAdmin) {
        return format!(
            "`{tool_name}` would make someone an admin, so a person needs to confirm exactly \
             who's being given the admin role before it goes ahead"
        );
    }
    // The manage-admin marker takes the same precedence: taking away someone's
    // admin role always needs a person to confirm exactly whose, in every
    // conversation state.
    if missing.contains(Capability::ManageAdmin) {
        return format!(
            "`{tool_name}` would take away someone's admin role, so a person needs to confirm \
             exactly whose role is being removed before it goes ahead"
        );
    }
    let reaches_out = missing.contains(Capability::ArbitraryEgress);
    let mutates = missing.contains(Capability::MutateExternal);
    match (reaches_out, mutates) {
        // Missing `MutateExternal` does not mean `tool_name` mutates — see
        // this function's doc comment for why.
        (true, true) => format!(
            "this conversation has taken in content from outside sources, so `{tool_name}` \
             needs a quick human check before it could send anything out or change anything \
             beyond this conversation"
        ),
        (true, false) => format!(
            "this conversation has taken in content from outside sources, so `{tool_name}` \
             needs a quick human check before it reaches an outside address"
        ),
        (false, true) => format!(
            "this conversation has taken in content from outside sources, so `{tool_name}` \
             needs a quick human check before it could change anything beyond this conversation"
        ),
        (false, false) => format!(
            "`{tool_name}` needs more access than this conversation currently has, so a \
             human check is needed first"
        ),
    }
}

#[cfg(test)]
mod tests;