Human-in-the-Loop (HITL)

How DefenseClaw turns confirmable findings into native approval prompts when a connector can pause, and what happens on connectors without an ask surface.

Human-in-the-Loop (HITL) changes a confirmable policy finding into an approval request only when the current connector event has a native ask surface. A supported event pauses in the agent UI while the operator approves or denies it. A connector without native ask cannot manufacture that pause: it applies its documented fallback and preserves raw_action: "confirm" for audit.

HITL is opt-in and only affects action mode. Observe mode records findings without enforcing them. CRITICAL findings reach the block threshold before HITL is considered and still block unconditionally with the default policy profile.

Guided example · Operator branch is pre-authored

Pause a HIGH-risk Claude Code action for review

A PreToolUse event becomes a native approval request, then follows a deterministic approve or deny branch.

Deterministic

Outcome

1{2  "connector": "claudecode",3  "decision": "approved",4  "operator_reason": "reviewed synthetic path change",5  "execution_resumed": true,6  "severity": "high"17}1{2  "connector": "claudecode",3  "decision": "approved",4  "operator_reason": "reviewed synthetic path change",5  "execution_resumed": true,6  "severity": "high"17}

DecisionApprove and continue

Reason

Operator approved the HIGH-risk action

Action

Audit and resume agent

What DefenseClaw did — and did not do

What it did

Pause a HIGH finding before execution
Use connector capability to choose native ask or downgraded confirm
Audit the chosen branch

What it did not do

Offer HITL in observe mode
Offer approval for CRITICAL findings
Execute either branch in the browser

What you just saw

A HIGH-risk Claude Code action paused at PreToolUse, where the connector can present a native approval. The Approve and Deny controls select pre-authored audit outcomes; the Codex control shows the downgraded-confirm path used when a connector can block but cannot ask natively. No action is executed in this page.

Two runtime outcomes

Native ask

The current hook event can prompt inside the agent UI. DefenseClaw maps confirm to the connector's ask response, and the host pauses until the operator approves or denies.

Explicit fallback

The current event cannot ask. Hook integrations normally return an alert or context message and preserve raw_action=confirm in audit; generic inspect clients may instead fail closed. There is no resumable approval in the DefenseClaw TUI.

Per-connector behaviour

Connector	Native ask events	Other confirm verdicts
OpenClaw	`before_tool_call`; plugin/chat-origin approval	Non-ask proxy surfaces use their route-specific enforcement behaviour
Claude Code	`PreToolUse`	Other hook events are demoted to a non-pausing response
Cursor	`beforeShellExecution`, `beforeMCPExecution`	Alert/context fallback; `raw_action` remains auditable
Copilot CLI	`preToolUse`	Alert/context fallback; `raw_action` remains auditable
Antigravity	`PreToolUse` (empirically verified)	Other registered lifecycle events are non-pausing telemetry/spec-parity surfaces
OmniGent	Pre-action `request`, `tool_call`, `llm_request` phases	Configured fallback for post-action phases
ZeptoClaw, Codex, Hermes, Gemini CLI, Windsurf, OpenHands, OpenCode	None	Connector-specific alert/allow/context fallback; no pause or TUI resume

For block events, fail-closed support, and the machine-readable source, see the Capability Matrix.

Configure

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

Prop

Type

With the default balanced thresholds, CRITICAL blocks, HIGH can become confirm when HITL is enabled, MEDIUM alerts, and LOW allows. Without HITL, HIGH is an alert rather than a silent block. A strict or custom policy pack can change those thresholds.

Decision flow

Policy thresholds run first. HITL only changes a non-blocked, confirmable finding, and a real pause requires native ask support on that event.

Operator workflow

The agent attempts an action and a pre-action hook reaches the gateway.

The gateway scores the action. If the result is below the block threshold but meets the configured HITL minimum, the raw policy action is confirm.

On a native-ask event, the connector renders its own approval prompt and pauses. Approving lets the host continue; denying stops the action.

On any other event, the connector applies its explicit fallback. The TUI and audit log can show the finding and raw_action, but they do not hold or resume that tool call.

What HITL is not

HITL is not a replacement for block rules or a tuned policy pack. Use unconditional blocks for actions that must never run, and use HITL only where the connector can actually ask and the operator has enough context to make a safe decision.