human-in-the-loop

# Human in the Loop

Place human judgment at the decision point where it changes risk. A confirmation dialog alone is not oversight: bind an authorized decision to an understandable, immutable action and preserve evidence of what happened.

## Inputs

Collect or infer, and label assumptions for:

- Agent goal, workflow states, and every action it can propose or execute
- Effect type, reversibility, value, affected people, and worst credible impact
- Data sensitivity, regulatory or contractual duties, and organizational risk tolerance
- Stable requester and approver subject identities, role assignments, policy owner, separation-of-duties rules, and coverage hours
- Required response time, timeout behavior, escalation contacts, and availability target
- Evidence an approver needs, including provenance, uncertainty, and alternatives
- Existing identity, policy, audit, ticketing, and notification systems
- Failure, retry, cancellation, compensation, and incident paths

Do not invent approver authority or organizational policy. If missing information affects a consequential action, produce a proposed policy and mark it for owner approval.

## Output contract

Deliver:

1. An action inventory and rationale-backed risk tier for each action
2. A gate policy defining validated predicates, eligible approver roles and distinct subjects, quorum, evidence, expiry, timeout, structured escalation, audit-outage behavior, execution-time reauthorization, compensation, break-glass, and separation of duties
3. A state machine for prepare, review, decision, execution, failure, and recovery
4. An approval experience that shows the exact action, material effects, uncertainty, provenance, alternatives, and safe reject/edit paths
5. An append-only decision record schema and retention/redaction requirements
6. Implementation or a file-level plan, plus policy and concurrency tests
7. Verification evidence, unresolved policy decisions, residual risk, and an operational recovery plan

Start from [assets/approval-policy-template.json](assets/approval-policy-template.json) when a machine-readable policy helps. Validate it with [scripts/validate_gate_policy.py](scripts/validate_gate_policy.py). Read [references/gate-design-guide.md](references/gate-design-guide.md) for risk-tier and state-machine guidance.

## Workflow

### 1. Inventory decisions and effects

List each agent action and the object it affects. Separate drafting, previewing, recommending, and reading from committing, sending, publishing, purchasing, deleting, granting access, executing code, or making a high-impact decision.

Record reversibility, scale, sensitivity, external visibility, financial value, time pressure, affected rights, and whether a mistaken action can be contained.

### 2. Assign the lightest sufficient oversight

Choose one control per risk:

- **Autonomous with audit:** bounded, reversible, low-impact actions
- **Notify after action:** low-impact actions where rapid awareness is sufficient
- **Review before action:** consequential or externally visible actions
- **Step-up approval:** value, sensitivity, confidence, anomaly, or scope crosses a threshold
- **Dual control:** critical, irreversible, privileged, or regulated actions; require at least two distinct approver subjects by default
- **Prohibited:** action exceeds policy or cannot be made acceptably safe

Do not gate every trivial step; excess prompts train users to approve reflexively. Never remove a required gate merely to meet a latency target. Treat critical single-control and requester self-approval as invalid by default. Permit either only through a time-bounded waiver that names the gate and exception type, includes the policy owner's stable subject ID and approval reference, documents rationale and compensating controls, and is explicitly referenced by the gate.

### 3. Specify the decision package

Show the approver:

- Plain-language intent and why the gate triggered
- Target identity and normalized parameters
- Before/after diff or exact proposed payload
- Expected effects, affected parties, cost, and reversibility
- Evidence sources, provenance, freshness, uncertainty, and known gaps
- Policy basis, alternatives, and what reject, edit, or timeout will do

Hide secrets and minimize personal data. Make the primary reject/cancel path as usable as approve.

### 4. Bind identity and approval to the action

Authenticate the approver and authorize their role independently of the model. Model roles and stable approver subjects separately so a two-role requirement cannot silently resolve to one person. Create a canonical representation or digest of actor, tenant, action, target, material parameters, policy version, expiry, and nonce. Approval applies only to that immutable proposal.

Invalidate approval after any material edit, expiry, policy change, target change, or relevant state change. Prevent self-approval where separation of duties applies. Do not interpret silence, message receipt, or a generic prior consent as approval.

### 5. Implement a safe state machine

Use explicit transitions such as:

`prepared -> pending_review -> approved | rejected | expired | cancelled`

`approved -> executing -> completed | failed | compensation_pending`

Make transitions atomic and idempotent. Recheck authorization and preconditions immediately before execution. Consume one-time approvals exactly once. Handle concurrent approvers, duplicate callbacks, stale screens, retries, and partial downstream failures.

### 6. Add escalation and recovery

Define machine-readable reminders, escalation subjects or roles, maximum attempts, maximum wait, exhaustion behavior, and out-of-office coverage. Default timeouts to deny, cancel, or escalate—not approve. Specify whether an audit-store outage fails closed or uses a short, signed buffer; critical actions fail closed. Reauthorize identity, role, policy, proposal digest, target state, and expiry immediately before execution.

Define compensation as a