Crate polyc_capability 

Capability taxonomy, derivation functions, and the pure gate decision engine (#587, #591).

One tool call requires a set of Capabilitys (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.
• An operator-declared taint-resilient set survives that subtraction, and only when the policy declares it (GrantPolicy::taint_resilient).
• 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.

Structs

CallPolicy

The per-call policy verdicts decide folds into the one outcome.

CapabilitySet

A set of Capabilitys. Small, Copy, and closed under the usual set algebra — the decision engine works only through these operations.

GrantPolicy

The agent’s configured capability policy — the operator-controlled half of grant derivation.

ToolProfile

The classification inputs for one tool: its spec’s MCP-style annotations plus its registry provenance.

Enums

ArgTransform

An argument transform the argument-aware dispatch policy asked for, honored only when the call is otherwise allowed.

Capability

One thing a tool call can do — the unit of the containment model.

GateOutcome

The single unified gate result for one tool call — replaces both the argument-aware ToolDecision and the needs_approval/override booleans.

TaintState

Whether untrusted content is in the conversation’s context at this gate decision.

ToolOrigin

Where a tool comes from — the registry-provenance half of classification.

Constants

NATIVE_SEARCH_GROUNDING

Scoping/audit name for the LLM provider’s native web-search-grounding primitive (issue #1226).

TAINT_REVOKED

The capabilities that untrusted content in context revokes: both channels that carry model-authored bytes to destinations an attacker may read.

Functions

decide

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.

escalation_reason

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).

granted_capabilities

Derive the capabilities granted to one gate decision from the agent’s policy and the provenance state at that moment.

monotonic_redeclaration

Clamp a re-declared profile so a connector’s runtime annotation change can only ever ADD required capabilities (#598).

required_capabilities

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.