Verdicts & Approval

Each verdict asks the caller for a different next action

Read a verdict under the contract of the entry point that returned it. A portable decision, a hosted execution, and a parked request have different effects.

A portable Allow dispatches nothing; a hosted response carries its own execution and evidence fields. A pre-dispatch Deny stops execution on that mediated path, and the change goes through the authorized workflow. A resumed request is revalidated before it runs.

The pricing service shows all three on one policy, plus the outcome readers do not expect: an Allow whose output is rewritten before the agent reads it. A case table pins each one, so a policy change that moves a call from one verdict to another fails in CI.

policy: ./policy.yaml
server: pricing
cases:
  - name: quote for sku-118
    tool: quote
    params: {sku: sku-118, percent: 10}
    expect: allow
  - name: refund above the ceiling
    tool: refund
    params: {order: order-77, amount: "120.00"}
    expect: deny
    code: refund-ceiling
  - name: discount of 80 percent on sku-301
    tool: discount
    params: {sku: sku-301, percent: 80}
    expect: pending
  - name: quote that would leak a customer email
    tool: quote
    params: {sku: sku-118, percent: 10}
    output: {price: "17.99", contact: "priya@harbor-goods.example"}
    expect: redact

chio policy test verdicts.test.yaml

policy   ./policy.yaml
PASS  quote for sku-118                        allow
PASS  refund above the ceiling                 deny     rule refund-ceiling
PASS  discount of 80 percent on sku-301        pending  approval: Mara Okafor
PASS  quote that would leak a customer email   redact   secret-leak on contact
4 cases: 4 passed

The fourth case is an Allow: the tool ran, and the output hook replaced the address before delivery. The effect has already happened by then, which is why output controls redact and never refuse. Response Sanitization covers the hook.

A transport or storage error is a possible result too, and it grants nothing. If dispatch may already have happened, inspect the hosted operation state before retrying an effect. The Node Runtime Contract owns execution and persistence.

Both crates declare three values; the core produces two

Verdict is declared twice, once in the portable core and once in the hosted shell, with the same three variants, the same derives, and no re-export between them. The core's copy states the asymmetry in its own doc comment:

/// Three-valued outcome of a kernel evaluation step.
///
/// This mirrors `chio_kernel::runtime::Verdict` exactly. The
/// kernel core never emits `PendingApproval` itself; the full `chio-kernel`
/// orchestration shell wraps the core verdict with the human-in-the-loop
/// approval path where needed.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Verdict {
    /// The action is allowed.
    Allow,
    /// The action is denied.
    Deny,
    /// The action is suspended pending a human decision. Only produced by
    /// the full `chio-kernel` shell, never by `chio-kernel-core` directly.
    PendingApproval,
}

Guards, adapters, and wire types all round-trip through the same enum, so the core names the third value and refuses it. chio_kernel_core::evaluate and its four floor variants return only Allow and Deny, as the field doc on EvaluationVerdict.verdict states.

Two traits are named Guard. The portable one returns Result<Verdict, KernelCoreError> and sees a PortableToolCallRequest with no DPoP proof, governed intent, approval token, or model metadata. The shell one returns Result<GuardDecision, KernelError>, carries GuardEvidence beside the verdict, and adds the dispatch-revalidation hooks; every guard in chio-guards implements it. The browser adapter, the mobile FFI, the C++ kernel FFI, the Lambda extension, and the conformance hot-path tests all pass an empty guard slice, &[], so on those paths the third value has no source.

Read more in Core & Shell.

A guard that returns PendingApproval is refused on both sides

In the core, step four of finish_verified_evaluation is the whole rule. Continuation needs two independent yeses:

for guard in input.guards {
    let evaluation = guard.evaluate(&ctx);
    let step = match &evaluation {
        Ok(verdict) => GuardStep::from(*verdict),
        Err(_) => GuardStep::Error,
    };
    let projected_allows = guard_step_admits(step);
    if guard_projection_allows_continuation(projected_allows, step)
        && matches!(&evaluation, Ok(Verdict::Allow))
    {
        continue;
    }

    match evaluation {
        Ok(_) => {
            // PendingApproval is reserved for the full kernel orchestration
            // layer (chio-kernel::approval::ApprovalGuard); if a sync guard
            // surfaces it here we fail closed.
            let core_err = KernelCoreError::GuardDenied {
                guard: guard.name().to_string(),
            };
            return deny(core_err, Some(matched_grant_index), Some(verified));
        }
        Err(error) => {
            let core_err = KernelCoreError::GuardError {
                guard: guard.name().to_string(),
                reason: error.deny_reason(),
            };
            return deny(core_err, Some(matched_grant_index), Some(verified));
        }
    }
}

GuardStep::from(Verdict::PendingApproval) is GuardStep::Error, so the pure projection says no: guard_step_admits runs the step through guard_pipeline_allows, whose kernel is core_authorized && guard_allows, with guard_allows true only for GuardStep::Allow. The observed result must also be Ok(Verdict::Allow), and guard_projection_allows_continuation fails closed when the projection and the observation disagree in either direction.

The core's deny is KernelCoreError::GuardDenied, reading guard "pending-guard" denied the request, so on the core path a pending guard and a denying guard produce one string, and no later guard runs. The hosted shell reaches the same refusal by its own loop and keeps the distinction in the reason. evaluate_guards_sequential serves both the inline path and the spawn_blocking offload in run_guards_owned, so the two cannot drift, and it reports returned an unsupported approval verdict. A GuardPipeline that propagates a child's pending value is refused under the name guard-pipeline.

Verdict::PendingApproval => {
    // The `Guard` trait does not carry the HITL approval flow; that runs via
    // `ApprovalGuard::evaluate`. A `Guard` returning `PendingApproval` is an
    // unsupported state, so fail closed.
    return Err(GuardRunError::new(
        KernelError::GuardDenied(format!(
            "guard \"{}\" returned an unsupported approval verdict",
            guard.name()
        )),
        evidence,
    ));
}

Read more about content-review, the one catalog guard that returns the third value.

Budget admission parks a call before dispatch

For each matched grant the async evaluation core and the nested-flow path run governed-admission validation, the guard pipeline, the runtime admission hook, then check_and_increment_budget. Only that last step returns BudgetAdmissionOutcome::PendingApproval: when the budget store answers BudgetAuthorizeHoldDecision::ApprovalRequired for a RequireCumulativeApprovalAbove constraint and the request carries no approval_tokens. The guard pipeline receives Some(matching.index) from the scope-match loop, and budget admission runs after it.

A matched grant with a cumulative constraint takes the structured path in begin_durable_tool_admission, and the kernel parks the call only on a node wired for durable admission. Each of these is a hard deny:

• The durable admission mode does not cover the request's effect class: aggregate, cumulative, and supplemental authorization requires durable admission coverage.
• No durable admission runtime is attached: no qualified admission operation store is configured.
• The grant carries more than one cumulative constraint: a matching grant must contain exactly one cumulative approval constraint.
• The negotiated peer profile lacks cumulative_approval_budget: cumulative approval budgets were not negotiated. The local profile turns the feature on; a request with a federated_origin_kernel_id uses the pinned peer profile, which must advertise it.
• A monetary call has no qualified payment adapter with a recoverable rail identity.

Before it parks, the kernel runs release_runtime_admission_reservations_for_pre_dispatch_denial and requires the release to be confirmed. A retained lease turns the outcome into a deny reading durable admission failed: runtime admission reservation retained on pending approval, so no reservation is held open for the length of an approval window.

A parked call returns its proposal and signs a deny

build_pending_approval_response_with_metadata builds the one response that carries the third value, from top-level and nested-flow evaluation. Every field is fixed:

• Verdict: PendingApproval.
• Output: the serialized ThresholdApprovalProposal, the artifact the caller gets signed.
• Reason: None, and no execution nonce is issued.
• Terminal state: Incomplete { reason: "approval_required" }.
• Receipt: Decision::Deny { reason: "cumulative approval required", guard: "kernel" }, with a threshold_approval metadata block carrying the proposal id, hash, deadline, and the state approval_required.

The receipt's Decision is a separate type with four values, Allow, Deny, Cancelled, and Incomplete, so never decode it as the in-flight verdict. Reconstruct a parked call from its threshold_approval metadata. The Receipt Contract lists the decision values.

Approval constraints stay with the hosted kernel. The core denies a cumulative-approval scope on evaluate_with_full_floor and evaluate_with_full_floor_and_root with capability feature unsupported on this runtime: cumulative approval enforcement. On evaluate and evaluate_with_crypto_floor, portable scope matching treats RequireApprovalAbove and RequireCumulativeApprovalAbove as unevaluable and fails with portable kernel cannot safely evaluate require_approval_above, so a grant carrying either denies on every core-only adapter.

Read more in Approval & HITL, and apply it in Require Human Approval.

Next: follow a parked call to its approval