Decision
The output of policy evaluation. What the runtime enforces.
Definition
A Decision is what a policy returns. The runtime enforces it. There is no ambiguity: the Decision is the contract between policy and runtime.
Start with two types. That is enough to build the first control loop:
from brane import Decision
Decision(type="allow")
Decision(type="deny", reason="Only SELECT queries are allowed")Decision Types
| Type | Status | Effect |
|---|---|---|
| allow | Implemented | Execute the capability. The function runs normally. |
| deny | Implemented | Block the capability. Raises CapabilityDeniedError. The function does not execute. |
| approval_required | Planned | Pause the action until a human approves. Requires an ApprovalProvider. |
| redact | Planned | Allow execution but hide or remove fields from the output before returning it. |
| transform_input | Planned | Mutate the input before executing. Useful for disabling side effects or normalizing arguments. |
| transform_output | Planned | Mutate the output after executing. Useful for enrichment or sanitization. |
| route | Planned | Redirect the action to a different capability, model, or provider. |
| sandbox | Planned | Execute with constrained access: restricted network, filesystem, time, or memory. |
| log_only | Planned | Allow execution and record the action for review without blocking. |
Fields
| Field | Type | Description |
|---|---|---|
| type | str | The decision type. See types below. |
| reason | str | None | Human-readable reason. Included in CapabilityDeniedError.reason. |
| decision_id | str | Unique ID for this decision. Auto-generated. |
| action_id | str | None | The action this decision applies to. |
| policy_name | str | None | Name of the policy that produced this decision. |
| policy_version | str | None | Version of the policy that produced this decision. |
| mutations | dict | None | Mutation payload for transform/redact decisions. Planned. |
| approval | dict | None | Approval request payload. Planned. |
| audit | dict | None | Audit metadata to attach to the action record. Planned. |
| metadata | dict | Arbitrary metadata. |
Computed Properties
allowed—Trueiftype == "allow"denied—Trueiftype == "deny"requires_approval—Trueiftype == "approval_required"
Composition Rules
When multiple policies match a capability, the engine composes their decisions:
- No policies match: allow by default.
- Any matching policy denies: return that deny decision immediately.
- All matching policies allow: return the last allow decision by priority order.
Only allow and deny participate in composition today. Future decision types (approval_required, redact, etc.) will have their own composition rules.
Examples
Allow with metadata:
Decision(type="allow")Deny with reason:
Decision(
type="deny",
reason="Refund amount exceeds tenant limit of $100",
)Deny with policy attribution:
Decision(
type="deny",
reason="High-risk tool blocked in prod",
policy_name="block_high_risk_prod",
policy_version="1.2",
)@runtime.before_capability decorator, the policy name and version are set automatically from the decorator arguments and annotated onto the Decision via policy.annotate(decision). You do not need to set them manually.Future Decision Space
The Decision type space is intentionally structured for expansion. As the runtime gains capability, the control surface grows:
approval_required: pause the action, send an ApprovalRequest, resume when a human approves or deny when they rejectredact: strip or mask sensitive fields from the output before returning ittransform_input: mutate the input before execution — useful for disabling a side effect (send_email(..., log_to_crm=false))transform_output: mutate the output after executionroute: redirect to a different model, tool, or capabilitysandbox: execute with constrained network, filesystem, or time accesslog_only: allow but record for later review — useful for shadow mode rollout of a new policy
The important property is that the decision is structured. A structured decision can be audited, composed, explained, and eventually served from a central policy system.