$worker

approval-gate

Name: approval-gate
Author: iii

v1.0.6

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

iiiverified

71 installs43 in 7d0 today

install

$iii worker add approval-gate@1.0.6

binaryapproval human-in-the-loop permissions policy security

macOS: arm64 · x64
Linux: arm64 · armv7 · x64
Windows: arm64 · x64 · x86

14functions 2triggers 0skills 4deps v1.0.6version

repoiii-hq/workers

exact versions are immutable; binary and bundle artifacts are digest-pinned.

functions

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
  … expand 2 nestedcollapse
  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
  … expand 2 nestedcollapse
  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
  … expand 2 nestedcollapse
  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
  … expand 2 nestedcollapse
  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[]
… expand 2 nestedcollapse
textstringrequired
typestringrequired
detailsobject
… expand 1 nestedcollapse
errorany of
… expand 2 nestedcollapse
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[]
… expand 2 nestedcollapse
textstringrequired
typestringrequired
detailsobject
… expand 1 nestedcollapse
errorany of
… expand 2 nestedcollapse
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"`.
  … expand 2 nestedcollapse
  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"`.
  … expand 1 nestedcollapse
  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
  … expand 2 nestedcollapse
  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
  … expand 2 nestedcollapse
  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
  … expand 2 nestedcollapse
  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
  … expand 2 nestedcollapse
  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
  … expand 2 nestedcollapse
  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
  … expand 2 nestedcollapse
  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

triggers

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