Documentation | HUMΛN Docs

# Org autonomy profiles

Every org chooses how much machine autonomy to allow before HumanOS requires explicit human approval. The profile lives on cp_orgs.autonomy_profile and is loaded on each agent execution by @human/agent-runtime.

Overview

Profile	Behavior
`paranoid`	Every muscle invocation requires human approval — regardless of risk or reversibility.
`balanced`	Default. Critical risk always gated; high risk gated when irreversible; low/medium proceed when delegation allows.
`aggressive`	Only critical risk requires approval.

Runtime enforcement is in MuscleContextImpl (packages/agent-runtime/src/context/muscle-context-impl.ts), fed by loadOrgAutonomyProfileFromDb (packages/agent-runtime/src/org-autonomy-profile.ts).

Why this matters

Sovereignty: humans set org-wide guardrails, not per-prompt vibes.

Fourth Law: low confidence escalates separately — autonomy profile gates *action*, not *uncertainty*.

Provenance: autonomy overrides are metered (agent.autonomy.override).

Set org profile (Control Plane)

SDK:

Valid values: paranoid, balanced, aggressive. Missing or invalid DB values fall back to balanced.

Runtime loading (agent authors)

Agent runtime reads the profile once per execution context:

import { loadOrgAutonomyProfileFromDb } from '@human/agent-runtime';// Called inside AgentRuntime.createExecutionContext()
const profile = await loadOrgAutonomyProfileFromDb(db, orgDid);
// → 'paranoid' | 'balanced' | 'aggressive'

Approval gating logic (simplified):

// packages/agent-runtime/src/context/muscle-context-impl.ts
function requiresHumanApproval(profile: AutonomyProfile, riskLevel: string, reversible: boolean) {
  switch (profile) {
    case 'paranoid':
      return true;
    case 'balanced':
      if (riskLevel === 'critical') return true;
      return riskLevel === 'high' && !reversible;
    case 'aggressive':
      return riskLevel === 'critical';
  }
}

When approval is required, muscles escalate via ctx.muscles → /v1/approvals or Command Plane escalations (see Human-in-the-Loop).

Per-agent override

Org profile is the default. Individual agents can override:

human api PUT "/v1/control-plane/agents/$AGENT_DID/autonomy" \
  --body '{"autonomy_level":"supervised"}'

Use org profile for policy; agent override for exceptions (e.g. read-only monitor agent on a paranoid org).

Use cases

Finance org — paranoid during month-end close; relax to balanced afterward.

Internal dev sandbox — aggressive for reversible low-risk connector calls.

Enterprise default — balanced at org creation; audit autonomy ratio via Command Plane diagnostics.

Security considerations

DO

Set org profile explicitly before enabling autopilot marketplace presets

Pair aggressive profiles with narrow delegations and provenance logging

DON'T

Assume aggressive means skip Fourth Law escalation on low confidence

Let client code downgrade requires_approval on Companion intent_action

Org autonomy profiles