Approval & HITL

ApprovalRequest

The serializable record persisted in the store and dispatched to channels. When the approval path needs a decision, it constructs an ApprovalRequest that the configured approval service stores; the host connects notification channels, the human interface, and resubmission. The request carries what a person needs to decide and what the kernel needs to validate the returned token:

pub struct ApprovalRequest {
    /// Unique request identifier. Caller-stable so the approval store
    /// can be keyed on this value. Callers should supply a UUIDv7.
    pub approval_id: String,

    /// The policy / grant identifier that triggered the approval.
    pub policy_id: String,

    /// The calling agent's identifier.
    pub subject_id: AgentId,

    /// Capability token ID bound to this request.
    pub capability_id: String,

    /// Public key of the capability subject this approval is bound to.
    /// A presented approval token must carry the same subject.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub subject_public_key: Option<PublicKey>,

    /// Server hosting the target tool.
    pub tool_server: ServerId,

    /// Tool being invoked.
    pub tool_name: String,

    /// Short action verb for human summaries (e.g. `invoke`, `charge`).
    pub action: String,

    /// SHA-256 hex digest of the canonical JSON of the tool arguments
    /// / governed intent. Used to bind an approval token to this exact
    /// parameter set; a mutated argument payload will not satisfy the
    /// same approval.
    pub parameter_hash: String,

    /// Unix seconds after which the request auto-denies (or escalates,
    /// per `timeout_action` in the grant).
    pub expires_at: u64,

    /// Hint for channels about where the human can respond (e.g. the
    /// URL of the dashboard or a Slack permalink). `None` means
    /// "dispatcher will fill this in after sending".
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub callback_hint: Option<String>,

    /// Unix seconds when the request was created.
    pub created_at: u64,

    /// Short human-readable summary for dashboards.
    pub summary: String,

    /// Original governed intent, when one is bound. Required for
    /// threshold-based approvals so the approver sees the financial
    /// envelope they are signing off on.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub governed_intent: Option<GovernedTransactionIntent>,

    /// Public keys allowed to approve this request. The kernel fails
    /// closed when the set is empty or when the presented approver is
    /// not in the set.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub trusted_approvers: Vec<PublicKey>,

    /// Guards that triggered the approval requirement.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub triggered_by: Vec<String>,
}

parameter_hash is computed with compute_parameter_hash over the canonicalized envelope of {server_id, tool_name, arguments, governed_intent}. An argument payload changed after approval fails the original token, because the hash binds the decision to that exact parameter set.

HitlVerdict

pub enum HitlVerdict {
    /// Guard passes -- no approval required.
    Allow,
    /// Guard denies without an approval path (e.g. fail-closed).
    Deny { reason: String },
    /// Approval is required. Kernel should persist the request and
    /// return a 202-style response to the caller.
    Pending {
        request: Box<ApprovalRequest>,
        verdict: Verdict,
    },
    /// Approval was supplied with the request and passed verification.
    Approved { token: Box<ApprovalToken> },
}

The Pending and Approved variants box their payloads so the enum stays cheap to pass by value (clippy large_enum_variant). The kernel keeps Verdict Copy by lifting the approval payload into this sibling type in approval.rs. The public verdict carries the marker Verdict::PendingApproval, and callers that need the request payload read it from the richer HITL API.

The dedicated approval guard sits beside the generic guard pipeline. An ordinary guard that returns PendingApproval starts no approval, and the generic pipeline fails closed on it. Verdicts & Approval owns the enum: which components may construct the third value, and what every other runner does when it sees one.

pub enum Verdict {
    /// The action is allowed.
    Allow,
    /// The action is denied.
    Deny,
    /// The action is suspended pending a human decision. Look up the
    /// associated `ApprovalRequest` via the HITL API.
    PendingApproval,
}

ApprovalStore

The persistent contract for pending and resolved approvals. The trait is synchronous because the kernel hot path is synchronous, and implementations use memory or SQLite. The store prevents double resolution and keeps replay-token bookkeeping in its own transaction. Approval Store & Channels covers the tables on one node's disk, the resolve transaction, the channel dispatch path, and the batch and threshold collectors.

pub trait ApprovalStore: Send + Sync {
    /// Persist a new pending request. Idempotent on `approval_id`: a
    /// second call with the same id returns without error as long as
    /// the stored payload matches.
    fn store_pending(&self, request: &ApprovalRequest) -> Result<(), ApprovalStoreError>;

    /// Fetch a single pending approval by id.
    fn get_pending(&self, id: &str) -> Result<Option<ApprovalRequest>, ApprovalStoreError>;

    /// List all pending approvals matching the filter.
    fn list_pending(
        &self,
        filter: &ApprovalFilter,
    ) -> Result<Vec<ApprovalRequest>, ApprovalStoreError>;

    /// Mark a pending approval as resolved. Returns
    /// `ApprovalStoreError::AlreadyResolved` if the request has already
    /// been resolved (double-resolve protection) and
    /// `ApprovalStoreError::Replay` if the bound token has already been
    /// consumed on a different request.
    fn resolve(&self, id: &str, decision: &ApprovalDecision) -> Result<(), ApprovalStoreError>;

    /// Count approved calls for a given subject / grant pair. Used by
    /// `Constraint::RequireApprovalAbove` threshold accounting.
    fn count_approved(&self, subject_id: &str, policy_id: &str) -> Result<u64, ApprovalStoreError>;

    /// Record that a token (by `token_id` and `parameter_hash`) has
    /// been consumed. Used to reject replays of the same approval
    /// token across a restart. Implementations may also call this from
    /// [`resolve`]; exposing it on the trait lets the kernel do the
    /// replay check before persisting the resolution, which matters
    /// when the store is backed by SQLite and wants to run the check
    /// inside the transaction.
    fn record_consumed(
        &self,
        token_id: &str,
        parameter_hash: &str,
        now: u64,
    ) -> Result<(), ApprovalStoreError>;

    /// Returns `true` if the token has already been consumed.
    fn is_consumed(&self, token_id: &str, parameter_hash: &str)
        -> Result<bool, ApprovalStoreError>;

    /// Fetch the resolution record for a previously resolved approval.
    fn get_resolution(&self, id: &str) -> Result<Option<ResolvedApproval>, ApprovalStoreError>;
}

InMemoryApprovalStore is the reference implementation. It keeps three maps under RwLock and Mutex: pending requests, resolved rows, and a consumed-token set keyed on token_id ":" parameter_hash. SQLite is the durable path, and the trait stays synchronous so both backends share one call site. Independent nodes that share single-use enforcement need a backend with a cross-node transaction contract, which a local WAL file does not provide.

ApprovalStoreError

pub enum ApprovalStoreError {
    NotFound(String),
    AlreadyResolved(String),
    Replay(String),
    Backend(String),
    Serialization(String),
}

ApprovalChannel

A channel presents an ApprovalRequest to a person. The trait is synchronous; channels that need async I/O run a small dedicated runtime or block through ureq. Add your own by implementing ApprovalChannel. Two channels ship with the kernel.

A channel is a fire-and-forget sink. On a terminal failure (ChannelError::Transport, ::Remote, or ::Config) the kernel records a tracing::warn! and the request stays in the approval store, reachable through GET /approvals/pending. A programmatic approver that polls that route needs no channel, because the request already lives in the store.

WebhookChannel

A blocking HTTP POST of the ApprovalRequest to a configured endpoint, which integrations wire into their own dashboard or ticketing system. The default timeout is 5s, with an optional static auth header (HMAC or bearer). The payload is a stable JSON envelope:

pub struct WebhookPayload<'a> {
    pub event: &'static str,
    pub approval: &'a ApprovalRequest,
    pub callback_url: String,
}

The channel fills event with approval_requested and callback_url with /approvals/{id}/respond (approval_channels.rs:74).

RecordingChannel

An in-memory channel used by tests, host adapters, and the api-poll dispatch mode. It captures every dispatched request in an in-memory ring, and tests assert on captured() that a dispatch fired without standing up an HTTP listener.

GovernedApprovalToken

The governance-token contract, defined in chio-core-types::capability:

pub enum GovernedApprovalDecision {
    Approved,
    Denied,
}

The signable body binds one approver, one subject, one intent hash, and one request ID:

pub struct GovernedApprovalTokenBody {
    pub id: String,
    pub approver: PublicKey,
    pub subject: PublicKey,
    pub governed_intent_hash: String,
    pub request_id: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub threshold_proposal_hash: Option<String>,
    pub issued_at: u64,
    pub expires_at: u64,
    pub decision: GovernedApprovalDecision,
}

A receiver verifies the decision from the approver's signature and the request binding, without trusting the kernel that created the request. The approver signs {request_id, governed_intent_hash, subject, decision, expires_at} with their key, the kernel matches the signature against the request's trusted_approvers, and the receipt records the approver's public key for attribution. The signed token as stored and presented:

pub struct GovernedApprovalToken {
    pub id: String,
    pub approver: PublicKey,
    pub subject: PublicKey,
    pub governed_intent_hash: String,
    pub request_id: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub threshold_proposal_hash: Option<String>,
    pub issued_at: u64,
    pub expires_at: u64,
    pub decision: GovernedApprovalDecision,
    /// Signing algorithm. Absent means Ed25519 (the default).
    ///
    /// Informational: verification dispatches off the algorithm encoded in
    /// [`GovernedApprovalToken::signature`] and [`GovernedApprovalToken::approver`].
    #[serde(default, skip_serializing_if = "is_default_optional_algorithm")]
    pub algorithm: Option<SigningAlgorithm>,
    pub signature: Signature,
}

Token binding checks

ApprovalToken::verify_against runs these checks in order, and each failure refuses the token:

1. request_id matches the approval_id.
2. governed_intent_hash matches the request's parameter_hash.
3. The presented approver matches the token's embedded approver, and the subject of the call matches the token's subject.
4. The approver public key is in trusted_approvers.
5. issued_at ≤ now < expires_at.
6. The lifetime (expires_at - issued_at) is at most MAX_APPROVAL_TTL_SECS = 3600. The single-use replay registry pins to that ceiling, so a longer token could outlive its replay record.
7. The Ed25519 signature verifies against the approver key.

Caller-attached approvals: BoundToolInvocation

When a caller attaches a token itself, the argument binding comes from the governed intent. Give that intent a BoundToolInvocation body, which names the authorizing capability and the SHA-256 of the call's RFC 8785 canonical arguments; the token signs the intent's hash. Before dispatch, the kernel recomputes each binding from the submitted call and refuses a mismatch with KernelError::GovernedTransactionDenied:

• Arguments. npm test rewritten to npm test && curl ... no longer hashes to the intent's parameters_hash. Reordering object members leaves the hash unchanged.
• Tool or server. The intent's server_id and tool_name no longer match the call.
• Capability under the same subject. The intent's capability_id no longer matches the authorizing capability.
• Request or subject. The token's request_id or subject no longer matches the call or its capability.

The kernel test bound_tool_invocation_denies_parameter_mutation_with_valid_approval submits five altered argument sets under one valid approval and asserts a denial for each.

Resume entry point

The synchronous resume entry point is resume_with_decision:

pub fn resume_with_decision(
    store: &dyn ApprovalStore,
    decision: &ApprovalDecision,
    now: u64,
) -> Result<ApprovalOutcome, KernelError>;

The HTTP layer calls it behind POST /approvals/{id}/respond. It checks that the HTTP envelope's outcome matches the signed token's decision before it writes to the store, because a mismatched pair would otherwise flip resolved=true and corrupt threshold counters.

Batch approvals

A batch approval lets a person pre-approve a class of repetitive calls for a bounded window. BatchApproval carries a recorded approver, subject, and server and tool pattern (* wildcard or prefix), an amount cap per call and in total, a call-count cap, time bounds, and used counters. The store is BatchApprovalStore.

Matching a stored batch and recording its usage are separate operations, so the embedding authenticates batch creation and coordinates authorization with usage accounting; a match by itself reserves none of the remaining allowance. Approval Store & Channels describes the storage boundary.

pub struct BatchApproval {
    pub batch_id: String,
    pub approver_hex: String,
    pub subject_id: AgentId,
    pub server_pattern: String,
    pub tool_pattern: String,
    pub max_amount_per_call: Option<MonetaryAmount>,
    pub max_total_amount: Option<MonetaryAmount>,
    pub max_calls: Option<u32>,
    pub not_before: u64,
    pub not_after: u64,
    pub used_calls: u32,
    pub used_total_units: u64,
    pub revoked: bool,
}

find_matching takes a subject, server, tool, optional amount, and the current time, and returns the first unrevoked batch whose subject, patterns, time window, remaining call count, and amount fit the call. record_usage moves used_calls and used_total_units, and revoke ends a batch early. A host wires those calls into its approval path, chio-store-sqlite carries the durable implementation, and each batch's batch_id ties a batch-approved call back to the approval that covered it.

"Approve every pricing call for the next hour"
  server_pattern: "pricing"
  tool_pattern: "*"
  max_calls: None
  not_after: now + 3600

"Approve up to 20 order queries in the next 30 minutes"
  server_pattern: "orders"
  tool_pattern: "sql"
  max_calls: Some(20)
  not_after: now + 1800

"Approve refunds under $100 for 4 hours, max $500 total"
  server_pattern: "pricing"
  tool_pattern: "refund"
  max_amount_per_call: { units: 10000, currency: USD }
  max_total_amount:    { units: 50000, currency: USD }
  not_after: now + 14400

HushSpec human_in_loop rule

HushSpec configures approval with the human_in_loop rule, nested directly under the flat top-level rules: key. It compiles to Constraint::RequireApprovalAbove on the matching tool grants, and tools matched by require_confirmation collapse the threshold to 0, so they require approval at any amount.

hushspec: "0.1.0"
rules:
  human_in_loop:
    enabled: true
    require_confirmation: ["refund"]
    approve_above: 50000          # $500.00, integer minor units
    approve_above_currency: "USD"
    timeout_seconds: 900
    on_timeout: deny

Amounts are integer minor units, cents for USD. A second example gates every write and command and sets a $150 threshold:

rules:
  human_in_loop:
    enabled: true
    # Always require approval
    require_confirmation:
      - "write_*"
      - "run_command"
    # $150 proposed maximum or more
    approve_above: 15000
    approve_above_currency: "USD"
    # Wait up to 15 minutes
    timeout_seconds: 900
    # Deny when the deadline passes
    on_timeout: deny

on_timeout has the type HumanInLoopTimeoutAction, with two values: deny, the #[default], and defer, which keeps the request pending for a later human decision. The parser accepts these fields; optional values may be omitted, and defaulted fields take the parser's defaults:

The rules.human_in_loop schema carries the gate and the deadline. Quorum and escalation live outside it, and it has no per-grant approver list or per-approver contact block. trusted_approvers, channels, and the default TTL are configured on the Rust ApprovalGuard, and trusted_approvers arrives per call through ApprovalContext::trusted_approvers:

let guard = ApprovalGuard::new(store)
    .with_channel(Arc::new(WebhookChannel::new(
        "https://kernel.larkfield.example/approvals/inbox",
    )))
    .with_default_ttl(1800);

Threshold approver resolution errors

Resolution refuses in four ways, all CompileError::Invalid:

• threshold approvers require an authenticated approver directory: no directory was supplied, so approver identifiers would be strings nobody vouched for.
• threshold approver `{id}` could not be resolved: the directory has no entry for a named approver. The directory's own error is appended.
• threshold approver directory changed identifier `{id}`: the directory answered with a different identifier than the one asked for. This substitution check keeps a directory from swapping who is on the approver set.
• threshold approvers did not resolve from one versioned directory: a resolved identity carried an empty directory version, or two approvers came from different versions. The whole set comes from one snapshot.

Policy compilation covers the pass this runs in.

Threshold requirement resolver

A host can also install a ThresholdApprovalRequirement directly for a policy hash, server, and tool. The Execution application requires two of three keys (reviewer, release operator, and data steward) for publication/append within 900 seconds:

let requirement = ThresholdApprovalRequirement::new(
    policy(),
    2,
    eligible,
    "publication-directory-v1".into(),
    900,
)
.map_err(anyhow::Error::msg)?;
kernel.set_threshold_approval_requirement_resolver(Arc::new(
    move |hash: &str,
          server: &str,
          tool: &str|
          -> Result<Option<ThresholdApprovalRequirement>, String> {
        Ok(
            (hash == requirement.policy_hash && server == "publication" && tool == "append")
                .then(|| requirement.clone()),
        )
    },
));

With the reviewer's vote alone, the set is collecting: the collector refuses delivery below the threshold and no publication exists. The reviewer voting again under a new token ID is refused, because one key cannot supply a second approver. With the reviewer and the release operator the set is ready, and delivery returns the exact proposal and token set, which the host attaches to the original request for kernel admission.

Host integration checklist

A shared review workflow lets workers in different languages and models use one approval path, through the publishing desk's HTTP contract. Keep signing credentials on the trusted reviewer side and retain the original proposal until it reaches a terminal outcome.

1. Configure gated actions, trusted approvers, expiry, and durable approval storage.
2. Persist the exact request and show its complete contents to the reviewer.
3. Verify the signed decision's subject, hash, request binding, and time window, and consume it once.
4. Resubmit the stored request and handle a new refusal from current capability, policy, or budget checks.
5. Correlate proposal, decision, execution receipt, and protected resource. Test rejection, tampering, expiry, replay, and interrupted execution.

Performance class

A call without an approval constraint scans grant constraints, O(C). A token-presenting call performs one store lookup, one canonical-JSON hash, a fixed set of binding comparisons, and one Ed25519 verification. Creating an approval performs one canonical-JSON hash, one store insert, and N sequential channel dispatches, which extend admission time by their latency and configured timeouts. Budget for the whole channel sequence, including failure paths.