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

Show a native pause only where the connector supports it
Use connector capability to choose native ask or a review-only alert
Audit the chosen branch

What it did not do

Offer HITL in observe mode
Offer approval for CRITICAL findings
Resume a Codex hook from an alert or TUI review
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 its review-only alert/system-message path, which cannot resume the hook. 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	None authoritative (ask-capable schemas exist at `beforeShellExecution` and `beforeMCPExecution`)	Alert/context fallback; higher-priority hooks merge above the DefenseClaw user hook and `raw_action` remains auditable
Copilot CLI	`preToolUse`	Alert/context fallback; `raw_action` remains auditable
Antigravity	`PreToolUse` only	`PreInvocation` and `PostInvocation` are context-transform surfaces, `PostToolUse` is observation-only, and DefenseClaw returns allow for `Stop`. No permission-bypass override is claimed without persisted official-client evidence.
Amp	`tool.call` and model-bound `tool.result` in the active foreground thread	A background thread or unavailable plugin UI rejects the call or withholds the result safely
OmniGent	Pre-action `request`, `tool_call`, `llm_request` phases	Post-phase confirm is audited and continues without a pause; DENY may suppress onward-visible content but cannot roll back completed work
ZeptoClaw, Codex, Hermes, Devin, OpenHands	None	Connector-specific alert/allow/context behavior; no pause or TUI resume.
OpenCode	`permission.ask` intentionally unimplemented	No native ask or context injection claim; 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.