Human-in-the-Loop (HITL)

How DefenseClaw escalates risky tool calls to a human operator. Covers when HITL fires, how min-severity gates the prompt, and the per-connector difference between native ask and downgraded confirm verdicts.

Human-in-the-Loop (HITL) sits between observe (log only) and full enforcement. When a finding clears the configured severity, the agent pauses and waits for an operator decision — approve, deny, or supply a reason.

HITL is opt-in and only meaningful in action mode. It is mutually exclusive with observe mode; observe never blocks, so there is nothing to pause on.

Two delivery models

Native ask

The connector exposes a hook event that can prompt the operator inside the agent UI. The agent pauses; the operator clicks approve/deny; the agent continues. No context switch.

Downgraded confirm

The connector cannot natively prompt the operator, so DefenseClaw downgrades the verdict to confirm. The raw_action is preserved in the audit log and the operator approves via the DefenseClaw TUI / OpenClaw plugin instead.

Per-connector behaviour

Connector	Model	Surface
OpenClaw	Native ask + plugin	Plugin-mediated approval reaches the OpenClaw chat origin
Claude Code	Native ask	PreToolUse prompt inside Claude Code
Cursor	Native ask	beforeShellExecution + beforeMCPExecution prompts inside Cursor
GitHub Copilot CLI	Native ask	preToolUse prompt inside Copilot CLI
ZeptoClaw	Downgraded confirm	DefenseClaw TUI
Codex	Downgraded confirm	DefenseClaw TUI / OpenClaw plugin
Hermes	Downgraded confirm	DefenseClaw TUI
Gemini CLI	Downgraded confirm	DefenseClaw TUI
Windsurf	Downgraded confirm	DefenseClaw TUI

For the full machine-readable view see the Capability Matrix.

Configure

defenseclaw setup guardrail \
  --mode action \
  --human-approval \
  --hilt-min-severity high \
  --restart

Prop

Type

Decision flow

HITL is the difference between block and pause. CRITICAL findings always block; HIGH findings pause if HITL is on, otherwise block; LOW/MEDIUM never pause unless you opt in via --hilt-min-severity.

Operator workflow

The agent attempts a tool call. The PreToolUse / beforeShellExecution / fetch_request hook fires (whichever the connector exposes).

The hook reaches the gateway, which scores the action, finds a HIGH finding, and returns a pause verdict because HITL is on.

On native-ask connectors, the agent surfaces a prompt inside its UI. On downgraded-confirm connectors, the operator sees the pending action in defenseclaw tui (or the OpenClaw plugin queue).

The operator approves or denies. The decision is written to the audit log alongside the original finding.

The agent receives the decision and either runs the tool call or surfaces the deny reason to the user.

What HITL is not

HITL is not a replacement for a strong rule pack. CRITICAL findings should still block unconditionally — operators are slow, and CRITICAL exists for a reason. HITL is for the messy middle: actions that are usually fine but occasionally aren't.