Skip to content
Sign in

approval-gate

v1.1.5

Policy and decision surface for human-held function calls — pre_call gate, pending inbox, per-session permission settings, and two notification event functions.

Install

bash
iii trigger compose::add worker=approval-gate

Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.

approval-gate

The policy and decision surface for human-held function calls (spec). Four surfaces, one worker:

  1. The gate — approval::gate, a pre_call hook. At startup the worker observes the harness's harness::hook::on-pre-call with it. It evaluates per-session mode, allow-lists, and inline config rules, and answers continue, deny, or hold.
  2. The filesystem-access watch — approval::filesystem-access-watch, a post_call hook: the worker observes harness::hook::on-post-call with it for shell::* / coder::*. It watches for a jail-scope filesystem_access_request on a dispatch failure and converts it into a filesystem_access hold, so the raw rejection does not reach the model. See Folder-access grant watch below.
  3. The decision plane — approval::resolve plus the per-session settings RPCs (set_mode, add_always_allow, approve_always, …). Human/console only.
  4. The pending inbox — an ephemeral index of held calls (approval::list-pending / approval::get-pending) plus two event functions (approval::on-pending-created / approval::on-pending-resolved) that notification workers and UIs observe. PendingApprovalRecord.kind ("function" | "filesystem_access") tells a console which prompt to render.

The worker keeps no resolved-approval history: a record exists only while a call is held; every record has an explicit deletion path (resolve, turn abort, session delete). The transcript's function_result and the calls of approval::on-pending-resolved are the audit trail. Holds do not expire: they wait until a human resolves or the turn/session is purged.

Standalone caveat

This worker codes against the harness contracts (harness::hook::on-pre-call, harness::hook::on-post-call, harness::function::resolve, harness::on-turn-completed, harness::filesystem::grant/grants — see harness.md § Hooks / § API Reference) and session-manager's session::on-deleted. Its observers of the harness and session-manager functions stay pending while a sibling is not running and become active when the sibling registers its function, so start order does not matter: the worker boots and serves its RPCs either way. Lacking harness::filesystem::grant/grants specifically degrades approval::filesystem-access-watch alone (see Folder-access grant watch) — it never holds, the rest of the worker is unaffected. The configuration worker is the one hard dependency — it is enabled by default in the engine, and a failed register/fetch aborts boot. The integration suite exercises the harness surface against in-process fakes and, when the harness binary is available, the real harness worker.

Install

iii call compose::add worker=approval-gate

Quickstart

cargo build
./target/debug/approval-gate --url ws://127.0.0.1:49134

The authoritative config lives in the engine's configuration worker (no committed config.yaml); pass --config <file>.yaml only to seed the entry on its very first registration.

Hold → decide → release, from any client:

# A held call shows up in the inbox…
iii call approval::list-pending
# …a human allows it (the harness runs the released call)…
iii call approval::resolve session_id=s_1 function_call_id=c_1 decision=allow
# …or denies it with a reason the model can adapt to.
iii call approval::resolve session_id=s_1 function_call_id=c_1 decision=deny reason="not on prod"

Permission model

Per-session mode plus two allow-lists, evaluated in this order (ported unchanged from the proven implementation):

  1. approval::* / configuration::* target → deny (human_only_function, even under full — self-escalation defense)
  2. mode full → allow
  3. approved_always hit → allow (every mode — remembered human decisions)
  4. mode auto and always_allow hit → allow (dormant under manual)
  5. fall through to configuration rules (first match wins): allow → allow · deny → deny · no match → hold

When the configuration entry omits rules, the gate denies only this worker's own approval::* surface; every other call holds. On startup the worker seeds/backfills the stored entry so rules are editable in the console.

Event functions

Both are private functions: only this worker calls them, anyone may observe them, and each handler returns the event it is called with. Neither takes args; observers select events with filters on the event's fields. The worker calls each function only while something observes it. iii delivers each call to every observer whose filters match: fire-and-forget, at-most-once (drops are counted per function and reason) and unordered. Reconcile with one approval::list-pending call after a restart or a gap.

Function Args Called when Event (input and output)
approval::on-pending-created none; filter on input.session_id, input.session_metadata.<key> a call was held and its inbox record written (async, off the hook's hot path) PendingApprovalRecord & { status: "pending" } — redacted args, session context: self-sufficient for notification copy
approval::on-pending-resolved none; filter on input.session_id, input.session_metadata.<key> a pending call left the inbox (exactly once per record) PendingResolvedEvent { session_id, turn_id, function_call_id, function_id, outcome: "allow" | "deny" | "aborted", reason?, session_metadata?, resolved_at } — reason is the operator's, on deny

A multi-tenant notification worker observes only its own sessions by filtering on the record's denormalized session_metadata, and reads the event from the envelope's output with capture: ['output']:

iii.observe(
  {
    function_id: 'approval::on-pending-created',
    filters: { 'input.session_metadata.owner': { $eq: 'u_1' } },
    capture: ['output'],   // the target reads the event as payload.output
  },
  'notify::approval-requested',
)
iii.observe(
    Source::function("approval::on-pending-resolved")
        .filters(json!({ "input.session_id": { "$eq": session_id } }))
        .capture([Capture::Output]),
    "notify::approval-cleared",
);

The worker calls each function only while something observes it.

Folder-access grant watch

When a shell::* / coder::* call fails with a jail-scope error (S215, S220, C215, C220) whose message carries a filesystem_access_request=<json> tail, approval::filesystem-access-watch (a post_call hook, observed with on_error: "fail_open" so a crashed/absent watch never turns an already-decided result into a stuck call) converts the failure into a kind: "filesystem_access" pending record instead of letting the raw denial reach the model. The record's access_request: { requested_root, attempted_path, error_code } is what the console shows: "allow access to requested_root?".

Before holding, the watch stands down (delivers the original error, no prompt) whenever:

  • the offending dir is the session's own workspace (metadata.working_dir) or under it — that is a harness stamp hole, not something a grant fixes;
  • the harness already reports a durable grant covering the dir (harness::filesystem::grants) — shell rejecting anyway is a store/stamp skew, not something a re-ask resolves;
  • the user already denied this dir earlier in the session (approval_filesystem_access_denied/<session_id>);
  • the call has already been re-asked grant_reask_limit times (default 3, configurable — see below);
  • the harness doesn't implement the workspace-grant control plane at all (harness::filesystem::grants fails) — the watch stands down entirely rather than looping.

Resolving a filesystem_access record's allow decision takes an additional grant_scope (once | session | always, default once):

Scope Effect
once The release carries extra_roots: [dir] — trusted for just this one call.
session harness::filesystem::grant first (durable for the rest of the session), THEN release with no extra_roots — the harness stamps the grant on every subsequent call itself. Falls back to once-style extra_roots if the grant call fails, so the user's click still works.
always Same as session, PLUS a best-effort append of dir to the shell deployment configuration's fs.host_roots (configuration::get/configuration::set {id: "shell"}). A persist failure is logged and never blocks the release.

deny records the dir in approval_filesystem_access_denied/<session_id> (so the same session won't be re-asked about it again) before delivering a denial whose default reason mentions folder access specifically ("user denied folder access to <dir>" unless the operator supplies their own).

Degraded modes — the watch is entirely additive and fails toward "do nothing, deliver the original error":

  • No shell filesystem_access_request support (older shell/coder): the ladder never finds a hint, so filesystem-access-watch never holds — behaves as if it did not observe the hook at all.
  • No harness workspace-grant control plane (older harness): the "already granted?" check fails, so every candidate stands down — no holds, no prompts, just the original error.
  • Harness/console down when the hook fires: on_error: "fail_open" delivers the original error unchanged; nothing is stuck.

Configuration

The whole config — runtime wiring and deployment approval defaults — lives in the single engine configuration entry approval-gate (operator-edited through its explicit form in the Console's global Settings modal; reactive reload, no polling). There is no committed config.yaml. On first boot the worker seeds the entry with the built-in defaults (including rules) so the editor is pre-filled; existing stored values are never overwritten except to add a missing rules field.

{
  "default_mode": "manual",        // manual | auto | full — sessions with no stored settings
  "rules": [                       // first match wins; no match → hold
    "!approval::*",
    { "function": "state::get", "action": "allow", "modes": ["auto"] }
  ],
  "grant_reask_limit": 3           // approval::filesystem-access-watch re-asks per held call before standing down
}

configuration is a required boot dependency: the worker registers the schema and fetches the authoritative value at startup, and a failed register/fetch aborts boot (the gate must run on a known, authoritative policy surface, never a guessed one). When no value is stored yet the built-in defaults above are seeded and used. Every field hot-reloads on configuration::set — nothing requires a restart.

Agent exposure

Deny all approval::* and configuration::* functions to in-run agents: resolve would let an agent approve its own held calls, and the settings RPCs are self-escalation (the gate's human_only_function rule is the in-depth backstop). list_pending / get_pending are read-only and redacted, but they enumerate held calls across sessions — keep them off agent allow-lists too.

Local development & testing

cargo test                                   # lib suites: pure unit + engine-backed handlers
cargo test --test integration               # engine-backed; self-skips without the engine and state binaries
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
./target/debug/approval-gate --manifest      # registry-publish manifest

The engine-backed suites spawn a real engine (III_ENGINE_BIN or iii on PATH) with its configuration worker, run this repo's standalone state worker beside it (III_STATE_BIN, built with cargo build in state/), register the production surface in-process, and fake sibling RPCs where noted (session::get). With CARGO_BIN_EXE_harness pointing at a built harness binary, tests/harness_integration.rs additionally boots the real harness worker for cross-worker hold / sweep / resolve checks.

III_ENGINE_BIN=$(command -v iii) III_STATE_BIN=../state/target/debug/state cargo test

Architecture documentation

Deep documentation lives in architecture/: internals.md for maintainers (evaluation order, the emit-gate deletion mechanics, lazy seeding, engine facts the code depends on) and integration.md for consumers (the full function and event contract, the harness handoff, deployment notes, what not to do).

Search the registry

Find workers, kits and executables, or jump to a page.