Skip to content
Registry

approval-gate

v1.0.26

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

license: Apache-2.0approvalhuman-in-the-looppermissionspolicysecurity

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.

Functions16

approval-gate::configuration-id

Function

Returns this approval-gate instance's configuration entry ID, without its value.

Request
Empty object
Response
  • idstringrequired

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 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 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 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 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::evaluate

Function

Report what approval::gate WOULD decide for a function id (allow / deny / needs_approval) without deciding it: no pending record, no writes. Called by the harness before binding a trigger to an ordinary function, since a trigger-fired call runs outside any turn and cannot ask a human.

Request
  • argumentsunknown

    Call arguments, for deployments whose rules carry argument constraints. Defaults to `{}`.

  • function_idstringrequired

    The function id to evaluate.

  • session_idstringrequired

    Session whose effective settings apply (mode + always-allow list).

Response
  • reasonstring

    Why, for the non-allow verdicts.

  • verdictone ofrequired

    What [`crate::functions::gate`] WOULD answer for this call.

    one of (3)
    Variant 1
    valuestringenum allow
    Variant 2
    valuestringenum deny
    Variant 3
    valuestringenum needs_approval

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 nested
      • textstringrequired
      • typestringrequired
    • detailsobject
      Show 1 nested
      • errorany of
        Show 2 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 nested
      • textstringrequired
      • typestringrequired
    • detailsobject
      Show 1 nested
      • errorany of
        Show 2 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 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`, `C220`).

      • 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 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 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 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`, `C220`).

      • 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 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 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 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 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

Search the registry

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