Module approval 

Phase 3.4-3.6 human-in-the-loop (HITL) primitives.

This module houses the approval-request data model, the persistent approval-store contract, the approval guard that decides when a call needs human sign-off, and the async resume entry points used by the HTTP surface after a human responds. The design follows docs/protocols/HUMAN-IN-THE-LOOP-PROTOCOL.md.

Scope note (deviation documented in the phase report): the existing crate::runtime::Verdict is Copy and threaded through 5,000+ lines of kernel code. Rather than ripple a breaking change through every call site, this module exposes a richer HitlVerdict that carries the pending approval request when one is needed. The public Verdict enum still gains a PendingApproval marker variant so external callers can pattern-match on the three-way decision; the payload is returned separately via ApprovalGuard::evaluate and ChioKernel::evaluate_tool_call_with_hitl.

Structs

ApprovalContext

Context passed into ApprovalGuard::evaluate.

ApprovalDecision

Decision packet delivered by an approver.

ApprovalFilter

Filter for list_pending.

ApprovalGuard

The built-in HITL guard. Runs before the generic guard pipeline and decides whether a call passes straight through, requires approval, or was already approved by an accompanying token.

ApprovalRequest

A request for human approval, produced when the approval guard returns Verdict::PendingApproval. Designed to be serialized into the approval store and the webhook payload without further wrapping.

ApprovalToken

Lightweight “approval token” representation used inside the kernel. For HITL v1 this wraps the existing GovernedApprovalToken together with the approval request it satisfies, so consumers do not have to re-plumb the full governance type through every surface.

BatchApproval

Batch approvals let a human pre-approve a class of calls.

ChannelHandle

Handle returned by dispatch. Kernel records this alongside the request in the store so cancel can be called later.

InMemoryApprovalStore

Thread-safe in-memory ApprovalStore. Useful for tests and for ephemeral deployments where operators explicitly accept data loss on restart (the opposite of Phase 3.5’s durability contract; SQLite is the production path).

InMemoryBatchApprovalStore

In-memory BatchApprovalStore used in tests. Production backends should persist via SqliteBatchApprovalStore.

ResolvedApproval

Resolved-approval row retained for audit and replay protection.

Enums

ApprovalOutcome

Minimal approval decision recorded after a human responds.

ApprovalStoreError

Errors emitted by approval stores.

ChannelError

Errors returned by approval channels.

HitlVerdict

Outcome of running an approval guard against a tool call.

Constants

MAX_APPROVAL_TTL_SECS

Maximum lifetime (in seconds) permitted on a single approval token. Mirrors the MAX_APPROVAL_TTL_SECS documented in the HITL protocol section 15: the single-use replay registry’s TTL is pinned to this value so no token can outlive its replay entry.

Traits

ApprovalChannel

Contract a channel must satisfy to dispatch an approval request.

ApprovalStore

Persistent store for pending and resolved HITL approvals. The trait is intentionally synchronous because every concrete implementation in the kernel hot path today (in-memory, SQLite via rusqlite) is synchronous, and the kernel itself does not run on an async executor.

BatchApprovalStore

Store for batch approvals. Counterpart to ApprovalStore.

Functions

compute_parameter_hash

Compute the parameter hash that binds an ApprovalRequest to a specific set of arguments. Input is canonicalized via the existing sha256_hex(chio_core::canonical::canonical_json_bytes(..)) helper so independent kernels produce identical hashes.

resume_with_decision

Apply a resolved approval decision: verify the token, mark it consumed, persist the resolution, and return the final verdict that the kernel should treat as the outcome.