HITL approval: self-confirm vs. third-party approval

Human gates for high-risk actions split into two flows: the executor confirming inside the session, and another role approving a ticket (HITL). Events, APIs, and timeouts differ; mixing them causes coverage metrics to count self-approval as human approval.

Two flows

flowchart TD
  Ask[Tool permission ask] --> Rule{confirm_by}
  Rule -->|operator| Self[Self-confirm permission.reply]
  Rule -->|approver| Hitl[HITL ticket approval.decide]
  Self --> Ev1[permission.* audit]
  Hitl --> Ev2[approval.* audit]

Flow	Condition	Decision API	Audit events	Appears in approval inbox
Self-confirm	Executor releases inside the session	`permission.reply`	`permission.approve` / `reject`	No
Third-party approval	Another role approves	`approval.decide`	`approval.approve` / `reject` / `expire`, etc.	Yes

A session can escalate a matching rule to require HITL (for example a require_hitl wildcard). Permission rules themselves remain allow / deny / ask.

No self-approval (executor)

An operator cannot call the approval decision API. HITL tickets also cannot be decided via the self-confirm API. Rule: when the executor must not approve their own execution-style release request in the approval center, use the HITL role; self-approval is not counted in approval-flow metrics.

Approvers (approver / admin) can decide tickets. Approving a ticket you initiated is an open-source capability; approving tickets initiated by others requires an enterprise HITL feature license. Without a license, related decisions return 403 and the enterprise implementation is not loaded.

Timeouts: fail-closed

Channel	Environment variable	Default
Self-confirm	`AGENTFORGE_ASK_TIMEOUT_MS`	30 minutes
HITL	`AGENTFORGE_HITL_TIMEOUT_MS`	8 hours

0 disables the timeout. On timeout the request is rejected or the ticket expires — never auto-approved. always-style releases apply only to other self-confirms in the same session; they do not auto-release HITL, and they do not cross tenants or users.

Relation to metrics

HITL coverage must query approval.* and permission.* separately. See audit chain and HITL metrics. Product positioning: cross-process governance.

Related reading: