Human-in-the-Loop

Overview

Ensure critical decisions require explicit human approval before execution. Human-in-the-Loop (HITL) is HUMΛN's core philosophy: AI assists and proposes, humans decide and approve.

Why Human-in-the-Loop?

Safety: Prevent autonomous AI from making irreversible mistakes
Accountability: Humans remain responsible for decisions
Trust: Transparency and oversight build confidence
Compliance: Meet regulatory requirements for human oversight
Fourth Law: When confidence is low, escalate — do not fake certainty

Think of it like: Autopilot on a plane — it can fly, but the pilot stays in command.

Shipped HITL surfaces

There is no HumanOS.createTask / waitForApproval fantasy namespace. Use:

Surface	Purpose
`GET/POST /v1/approvals`	Approval inbox — list / respond
`client.controlPlane.escalations`	Command Plane escalations
`client.workforce.*`	Workforce work-items (assign / complete)
`humanCall` → `POST /v1/humanos/route`	Fourth Law escalation on route

SDK Examples

SDK:

Fourth Law escalation on route

When confidence is low, humanCall surfaces escalation instead of silently proceeding:

import { HumanClient, humanCall } from '@human/sdk';
import { EscalationRequiredError } from '@human/core';

const client = new HumanClient({
  delegationToken: process.env.HUMAN_DELEGATION_TOKEN!,
});

try {
  const result = await humanCall(
    client,
    {
      task_id: crypto.randomUUID(),
      task_type: 'invoice_approval',
      required_capabilities: ['accounting'],
      ai_assessment: { confidence: 0.4 },
      escalation_recommendation: true,
    },
    { delegation: process.env.HUMAN_DELEGATION_TOKEN! },
  );
  console.log(result);
} catch (err) {
  if (err instanceof EscalationRequiredError) {
    // Resolve via /v1/approvals or controlPlane.escalations.respond
    console.log('Fourth Law — human decision required');
  }
  throw err;
}

Workforce work-items as HITL queues

const orgDid = process.env.HUMAN_ORG_DID!;
const task = await client.workforce.createTask({
  org_did: orgDid,
  title: 'Approve invoice INV-2026-001',
  description: 'Finance manager review before payment',
  required_capabilities: ['accounting', 'invoice_processing'],
});
// Human completes in Console / workforce inbox, or:
await client.workforce.assign(task.work_item_id!, orgDid, 'did:human:finance-lead');
await client.workforce.complete(task.work_item_id!, orgDid, 'Approved');

Security Considerations

DO

Require human respond on irreversible actions

Log decision + comment on every approval response

Escalate on low confidence via humanCall / Fourth Law

DON'T

Do not invent HumanOS.createTask / waitForApproval / executeTask

Auto-approve high-risk actions without an approval record

Hide AI reasoning from approvers in the product UX

HITL approval inbox (alias: hitl-approval)

Community posts may link /docs/patterns/humanos/hitl-approval. That URL is an alias of this pattern. The approval inbox is the same surface:

Verb	Path
List	`GET /v1/approvals?status=pending`
Respond	`POST /v1/approvals/{id}/respond`
Bundle	`humanos.bundle.hitl.v1` prompt contributions (install via marketplace)

Prefer this page (human-in-loop) in new links.

Error handling and escalation

When a route cannot proceed safely, escalate — do not invent silent retries that hide uncertainty:

Catch EscalationRequiredError from humanCall (Fourth Law above).
Open or respond on /v1/approvals or client.controlPlane.escalations.
For durable work, pause async executions and resume after human respond (see Async jobs).

Sibling deep-dive: Error handling and escalation.