approval-gate

v1.0.8

Policy and decision surface for human-held function calls — pre_trigger gate, pending inbox, per-session permission settings, and two notification trigger types.

Published 3mo agoapproval human-in-the-loop permissions policy security

Install

bash

iii trigger compose::add worker=approval-gate@1.0.8

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

Functions14

approval::add-always-allow

Function

Add a function to the session's auto-mode trust list (idempotent). Human/console-only.

Request

function_idstringrequired
session_idstringrequired

Response

settingsobjectrequired
The stored per-session record (scope `approval_settings`). Reads compute the effective settings from configuration defaults when no record exists — see settings.rs.
- always_allowobject[]
  Consulted only in auto mode.
  function_idstringrequired
  granted_atinteger· int64required
  ms epoch
  granted_byone ofrequired
  Show 2 nestedHide nested
  one of (2)
  Variant 1
  valuestringenum user_click
  Variant 2
  valuestringenum seed
- approved_alwaysobject[]
  Consulted in every mode — remembered human decisions.
  function_idstringrequired
  granted_atinteger· int64required
  ms epoch
  granted_byone ofrequired
  Show 2 nestedHide nested
  one of (2)
  Variant 1
  valuestringenum user_click
  Variant 2
  valuestringenum seed
- modeall of
  all of (1)
  Variant 1
  valuestringenum manual, auto, full
- mode_set_atinteger· int64
  ms epoch

approval::approve-always

Function

Record a per-session 'approve always' grant (honoured in every mode). Human/console-only.

Request

function_idstringrequired
session_idstringrequired

Response

settingsobjectrequired
The stored per-session record (scope `approval_settings`). Reads compute the effective settings from configuration defaults when no record exists — see settings.rs.
- always_allowobject[]
  Consulted only in auto mode.
  function_idstringrequired
  granted_atinteger· int64required
  ms epoch
  granted_byone ofrequired
  Show 2 nestedHide nested
  one of (2)
  Variant 1
  valuestringenum user_click
  Variant 2
  valuestringenum seed
- approved_alwaysobject[]
  Consulted in every mode — remembered human decisions.
  function_idstringrequired
  granted_atinteger· int64required
  ms epoch
  granted_byone ofrequired
  Show 2 nestedHide nested
  one of (2)
  Variant 1
  valuestringenum user_click
  Variant 2
  valuestringenum seed
- modeall of
  all of (1)
  Variant 1
  valuestringenum manual, auto, full
- mode_set_atinteger· int64
  ms epoch

approval::clear-settings

Function

Drop the session's stored settings record (revert to configuration defaults).

Request

session_idstringrequired

Response

clearedbooleanrequired

approval::filesystem-access-watch

Function

post_trigger hook: watch shell::*/coder::* dispatch failures for a jail-scope filesystem_access_request and hold a filesystem_access pending approval for it. Called by the harness only.

Request

callany of
pre_trigger payload.
any of (2)
Variant 1
argumentsunknown
function_idstringrequired
idstringrequired
Variant 2
valuenull
depthinteger· int64
Sub-agent depth (hooks run for child turns too).
metadataobject
The per-send tracing metadata (`metadata.fs_scope.root` is the user-picked session workspace, absolute + canonical).
pointstring
resultany of
post_trigger payload: the function_result about to be delivered.
any of (2)
Variant 1
contentobject[]
Show 2 nestedHide nested
textstringrequired
typestringrequired
detailsobject
Show 1 nestedHide nested
errorany of
Show 2 nestedHide nested
any of (2)
Variant 1
codestring
messagestringrequired
Variant 2
valuenull
function_call_idstring
function_idstring
is_errorboolean
Variant 2
valuenull
session_idstringrequired
stepinteger· int64
turn_idstringrequired

Response

one of (3)

Variant 1

decisionstringrequiredenum continue

Variant 2

decisionstringrequiredenum deny
reasonstringrequired

Variant 3

decisionstringrequiredenum hold

approval::gate

Function

pre_trigger hook: evaluate the permission model and answer continue / deny / hold; writes the pending inbox record on hold. Called by the harness only.

Request

callany of
pre_trigger payload.
any of (2)
Variant 1
argumentsunknown
function_idstringrequired
idstringrequired
Variant 2
valuenull
depthinteger· int64
Sub-agent depth (hooks run for child turns too).
metadataobject
The per-send tracing metadata (`metadata.fs_scope.root` is the user-picked session workspace, absolute + canonical).
pointstring
resultany of
post_trigger payload: the function_result about to be delivered.
any of (2)
Variant 1
contentobject[]
Show 2 nestedHide nested
textstringrequired
typestringrequired
detailsobject
Show 1 nestedHide nested
errorany of
Show 2 nestedHide nested
any of (2)
Variant 1
codestring
messagestringrequired
Variant 2
valuenull
function_call_idstring
function_idstring
is_errorboolean
Variant 2
valuenull
session_idstringrequired
stepinteger· int64
turn_idstringrequired

Response

one of (3)

Variant 1

decisionstringrequiredenum continue

Variant 2

decisionstringrequiredenum deny
reasonstringrequired

Variant 3

decisionstringrequiredenum hold

approval::get-pending

Function

Read one pending record; null when resolved or unknown.

Request

function_call_idstringrequired
The function call id of the held call.
session_idstringrequired
The session the pending record belongs to.

Response

any of (2)

Variant 1

pendingobjectrequired
The inbox payload — shared by both triggers, `list_pending`, and `get_pending`. Self-describing (all ids inside the value) and notification-safe (arguments pass through redaction).
- access_requestany of
  Present only when `kind == "filesystem_access"`.
  Show 2 nestedHide nested
  any of (2)
  Variant 1
  attempted_pathstringrequired
  The raw offending path from the request, as sent by the caller.
  error_codestringrequired
  The jail-scope rejection code that produced this hint (`S215`, `S220`, `C215`, `C218`).
  requested_rootstringrequired
  Canonical root a grant should target (existing directory, or nearest existing ancestor directory of the offending path).
  Variant 2
  valuenull
- arguments_excerptunknown
  Redacted — safe to forward to notification channels.
- assistant_excerptstring
  First text block of the assistant message that contained this function_call. Best-effort; not derivable from `pre_trigger` `HookInput` in v1, so always omitted today.
- depthinteger· int64
  Sub-agent depth (0 = top-level), from `HookInput`.
- function_call_idstringrequired
- function_idstringrequired
- kindall ofrequired
  `"function"` or `"filesystem_access"`.
  Show 1 nestedHide nested
  all of (1)
  Variant 1
  one of (2)
  Variant 1
  valuestringenum function
  Variant 2
  valuestringenum filesystem_access
- pending_atinteger· int64required
  ms epoch
- session_descriptionstring
- session_idstringrequired
- session_metadataobject
  Tenancy + routing (trigger config filter target).
- session_titlestring
- turn_idstringrequired

Variant 2

valuenull

approval::get-settings

Function

Read the session's effective settings (stored record or configuration defaults); never writes.

Request

session_idstringrequired

Response

settingsobjectrequired
The stored per-session record (scope `approval_settings`). Reads compute the effective settings from configuration defaults when no record exists — see settings.rs.
- always_allowobject[]
  Consulted only in auto mode.
  function_idstringrequired
  granted_atinteger· int64required
  ms epoch
  granted_byone ofrequired
  Show 2 nestedHide nested
  one of (2)
  Variant 1
  valuestringenum user_click
  Variant 2
  valuestringenum seed
- approved_alwaysobject[]
  Consulted in every mode — remembered human decisions.
  function_idstringrequired
  granted_atinteger· int64required
  ms epoch
  granted_byone ofrequired
  Show 2 nestedHide nested
  one of (2)
  Variant 1
  valuestringenum user_click
  Variant 2
  valuestringenum seed
- modeall of
  all of (1)
  Variant 1
  valuestringenum manual, auto, full
- mode_set_atinteger· int64
  ms epoch
sourceall ofrequired
Whether a per-session record exists.
all of (1)
Variant 1
valuestringenum stored, defaults

approval::list-pending

Function

The pending inbox across sessions, with tenancy filters; the catch-up path for notification workers after a restart.

Request

cursorstring
Opaque.
limitinteger· uintmin 0
Default 50.
metadataobject
Equality match against `session_metadata` (tenancy).
session_idstring

Response

next_cursorstring
pendingobject[]required
Ordered by pending_at ascending.
- access_requestany of
  Present only when `kind == "filesystem_access"`.
  any of (2)
  Variant 1
  attempted_pathstringrequired
  The raw offending path from the request, as sent by the caller.
  error_codestringrequired
  The jail-scope rejection code that produced this hint (`S215`, `S220`, `C215`, `C218`).
  requested_rootstringrequired
  Canonical root a grant should target (existing directory, or nearest existing ancestor directory of the offending path).
  Variant 2
  valuenull
- arguments_excerptunknown
  Redacted — safe to forward to notification channels.
- assistant_excerptstring
  First text block of the assistant message that contained this function_call. Best-effort; not derivable from `pre_trigger` `HookInput` in v1, so always omitted today.
- depthinteger· int64
  Sub-agent depth (0 = top-level), from `HookInput`.
- function_call_idstringrequired
- function_idstringrequired
- kindall ofrequired
  `"function"` or `"filesystem_access"`.
  all of (1)
  Variant 1
  one of (2)
  Variant 1
  valuestringenum function
  Variant 2
  valuestringenum filesystem_access
- pending_atinteger· int64required
  ms epoch
- session_descriptionstring
- session_idstringrequired
- session_metadataobject
  Tenancy + routing (trigger config filter target).
- session_titlestring
- turn_idstringrequired

approval::on-config-change

Function

Internal: hot-reload approval-gate from the authoritative configuration when it changes — swaps the per-call snapshot (timeouts + approval defaults).

Request

idstring
Configuration id that changed (advisory; the handler re-fetches the value).

Response

okbooleanrequired

approval::on-session-deleted

Function

Internal: session::deleted handler (purge the session's settings and pending records).

Request

session_idstringrequired

Response

okbooleanrequired

approval::on-turn-completed

Function

Internal: harness::turn-completed handler (purge the turn's pending records).

Request

turn_idstringrequired

Response

okbooleanrequired

approval::remove-always-allow

Function

Remove a function from the session's auto-mode trust list (no-op when absent). Human/console-only.

Request

function_idstringrequired
session_idstringrequired

Response

settingsobjectrequired
The stored per-session record (scope `approval_settings`). Reads compute the effective settings from configuration defaults when no record exists — see settings.rs.
- always_allowobject[]
  Consulted only in auto mode.
  function_idstringrequired
  granted_atinteger· int64required
  ms epoch
  granted_byone ofrequired
  Show 2 nestedHide nested
  one of (2)
  Variant 1
  valuestringenum user_click
  Variant 2
  valuestringenum seed
- approved_alwaysobject[]
  Consulted in every mode — remembered human decisions.
  function_idstringrequired
  granted_atinteger· int64required
  ms epoch
  granted_byone ofrequired
  Show 2 nestedHide nested
  one of (2)
  Variant 1
  valuestringenum user_click
  Variant 2
  valuestringenum seed
- modeall of
  all of (1)
  Variant 1
  valuestringenum manual, auto, full
- mode_set_atinteger· int64
  ms epoch

approval::resolve

Function

Apply a human decision to a held call: release it for execution (allow) or deliver a denial (deny). Human/console-only.

Request

access_durationany of
Only meaningful when the target record is `kind: "filesystem_access"` and `decision: "allow"`. Defaults to `once`.
any of (2)
Variant 1
one of (3)
Variant 1
valuestringenum once
Variant 2
valuestringenum session
Variant 3
valuestringenum always
Variant 2
valuenull
decisionstringrequiredenum allow, deny
function_call_idstringrequired
reasonstring
Surfaced to the model on deny.
session_idstringrequired

Response

resolvedbooleanrequired
false: unknown/already-resolved pending call.
turn_resumedboolean
Passthrough from harness::function::resolve.

approval::set-mode

Function

Set the session's permission mode (manual / auto / full). Human/console-only.

Request

modestringrequiredenum manual, auto, full
session_idstringrequired

Response

settingsobjectrequired
The stored per-session record (scope `approval_settings`). Reads compute the effective settings from configuration defaults when no record exists — see settings.rs.
- always_allowobject[]
  Consulted only in auto mode.
  function_idstringrequired
  granted_atinteger· int64required
  ms epoch
  granted_byone ofrequired
  Show 2 nestedHide nested
  one of (2)
  Variant 1
  valuestringenum user_click
  Variant 2
  valuestringenum seed
- approved_alwaysobject[]
  Consulted in every mode — remembered human decisions.
  function_idstringrequired
  granted_atinteger· int64required
  ms epoch
  granted_byone ofrequired
  Show 2 nestedHide nested
  one of (2)
  Variant 1
  valuestringenum user_click
  Variant 2
  valuestringenum seed
- modeall of
  all of (1)
  Variant 1
  valuestringenum manual, auto, full
- mode_set_atinteger· int64
  ms epoch

Triggers2

approval::pending-created

Trigger

A function call was held for human approval and its inbox record written. Payload: PendingApprovalRecord (redacted args, session context, expiry). Bind notification workers here.

Invocation

metadataobject
Equality match against the record's `session_metadata` (every key given here must equal the stored value — subset match).
session_idstring
Only deliver events for this session.

Return

valueunknown

approval::pending-resolved

Trigger

A pending approval left the inbox (outcome: allow | deny | timeout | aborted). Emitted exactly once per record; lets UIs clear badges.

Invocation

metadataobject
Equality match against the record's `session_metadata` (every key given here must equal the stored value — subset match).
session_idstring
Only deliver events for this session.

Return

valueunknown

Install

Functions14

Triggers2

Search the registry