Hitl Safety

The Six HITL Handlers

Import handlers from the top-level namespace:

import { hitl } from '@framers/agentos';

hitl.autoApprove()

Always approves. Use only in development, testing, or when the security tier is permissive/dangerous and you trust all tool inputs.

hitl.autoReject(reason?)

Always denies with an optional reason string. Useful for locking down specific tools entirely.

hitl.cli()

Prompts the human operator in the terminal for a yes/no decision. Default handler when running wunderland chat interactively.

hitl.webhook(url)

POSTs the approval request to an external URL and waits for a JSON response with { approved: boolean, reason?: string }. Use for custom dashboards or external approval systems.

hitl.slack({ channel, token })

Sends an approval request to a Slack channel and waits for a reaction or thread reply. In v1, defaults to auto-approve after notification.

hitl.llmJudge({ model?, provider?, criteria?, confidenceThreshold?, fallback?, apiKey? })

Routes the approval decision through an LLM. The judge evaluates the pending action against the provided criteria string and returns approve/reject with a confidence score. When the confidence is below confidenceThreshold (default 0.7), the judge falls back to fallback (default: auto-reject).

Usage in agency():

agency({
  hitl: {
    handler: hitl.llmJudge({
      model: 'gpt-4o-mini',
      criteria: 'Is this action safe and relevant to the user request?',
      confidenceThreshold: 0.7,
    }),
  },
});

Usage in CLI:

wunderland chat --llm-judge

Usage in agent.config.json:

{
  "hitl": {
    "mode": "llm-judge"
  }
}

Guardrail Overrides

When guardrailOverride is true (the default), guardrails run after HITL approval and can veto actions that passed the approval gate. This provides defense-in-depth: even if a human or LLM judge approves an action, built-in safety checks still apply.

Built-in post-approval guardrail checks:

• code-safety — detects destructive shell patterns (rm -rf /, DROP TABLE, FORMAT C:)
• pii-redaction — detects SSNs, credit card numbers, and other PII in tool arguments

Even auto-approved actions (via hitl.autoApprove()) are checked when guardrailOverride is enabled.

Disable guardrail overrides:

// In API
agency({ hitl: { guardrailOverride: false } });

# In CLI
wunderland chat --no-guardrail-override

// In agent.config.json
{ "hitl": { "guardrailOverride": false } }

humanNode in Graph Orchestration

When building agent graphs with AgentOS orchestration, use humanNode() to insert approval gates:

import { humanNode } from '@framers/agentos/orchestration';

humanNode({
  prompt: 'Deploy to production?',
  timeout: 300000,           // 5 minutes
  onTimeout: 'reject',       // what happens when timeout expires
});

humanNode Options

LLM judge in a graph node:

humanNode({
  prompt: 'Deploy to production?',
  judge: {
    model: 'gpt-4o-mini',
    criteria: 'Is this deployment safe given the current test results?',
    confidenceThreshold: 0.8,
  },
  onTimeout: 'reject',
  timeout: 300000,
});

The Approval Flow

The full execution path for any HITL-gated action:

1. Tool invocation requested — the agent wants to call a tool
2. HITL decision — the configured handler (human, LLM judge, auto) evaluates the request
3. Guardrail check — if guardrailOverride is true, post-approval guardrails scan the action
4. Execute or deny — the tool runs only if both HITL and guardrails approve

If either step rejects, the agent receives a denial message with a reason and can adjust its approach.

Choosing the Right Handler

Security Tier Interaction

• Dangerous / Permissive — HITL is opt-in; most tools auto-approve
• Balanced — HITL gates destructive tools (file delete, shell execute with dangerous patterns)
• Strict — HITL gates all external and write tools; only read-only tools skip approval
• Paranoid — every tool invocation goes through HITL, no exceptions

Set the security tier in agent.config.json:

{
  "security": {
    "tier": "balanced"
  }
}

Or programmatically:

import { SecurityTiers } from '@framers/agentos/safety/runtime';
agency({ security: { tier: SecurityTiers.BALANCED } });

Best Practices

• Default to guardrailOverride: true — defense-in-depth catches what humans miss
• Use LLM judge for high-volume flows — humans cannot review hundreds of requests per minute
• Set meaningful criteria — vague criteria like "is this ok?" produce unreliable judge decisions
• Always set onTimeout — hanging approval gates block the entire agent pipeline
• Combine with PII redaction — ensure tool arguments are scanned for leaked secrets before execution
• Log all decisions — HITL decisions are audit-logged; review them periodically for pattern analysis
• Escalate on low confidence — configure the LLM judge fallback to escalate to a human when confidence is low rather than auto-rejecting