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?

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:

SDK Examples

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

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:

Error handling and escalation

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

Sibling deep-dive: Error handling and escalation.

Next Steps

See Also