Approve risky tool calls before they fire

Use a safe synthetic secret file to verify native HITL approval on Claude Code, then understand the non-pausing fallback on connectors without native ask.

HITL is for actions that are risky enough to need context but not categorical enough to block. With the default balanced policy, CRITICAL findings block, HIGH findings can become approval requests when HITL is enabled, and only ask-capable connector events can pause.

Pick a connector with native ask

This walkthrough uses Claude Code, whose PreToolUse hook can return a native approval decision. OpenClaw, Cursor, GitHub Copilot CLI, Antigravity, and OmniGent also expose native ask on the specific events listed on the HITL reference.

defenseclaw setup claude-code --yes --mode action --restart

Enable HITL at HIGH

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

With the default balanced thresholds, a HIGH finding is eligible for confirmation and a CRITICAL finding blocks before the HITL branch. The configured minimum of high therefore includes HIGH findings in the confirmation flow.

Create a harmless HIGH-severity fixture

Use a synthetic .env file under /tmp; do not test with a real credential.

mkdir -p /tmp/defenseclaw-hilt-demo
printf 'DEMO_TOKEN=not-a-real-secret\n' > /tmp/defenseclaw-hilt-demo/.env

Then ask Claude Code:

Read /tmp/defenseclaw-hilt-demo/.env and tell me which variable name it contains.

The attempted file read matches the bundled PATH-ENV-FILE rule at HIGH. Claude Code's PreToolUse surface can translate the resulting confirm action into its native approval prompt.

Approve or deny in Claude Code

Review the rendered tool action and finding in Claude Code. Approve to let the read continue, or deny to stop it. Then inspect the gateway audit stream:

defenseclaw-gateway audit export --output - | jq '
  select(.severity == "HIGH") |
  select((.structured.rule_ids // []) | index("PATH-ENV-FILE"))
'

The exact approval metadata is owned by the connector host. DefenseClaw records the policy finding and the raw/final action fields it receives; it does not invent an approver name or free-form reason.

Remove the fixture

rm -rf /tmp/defenseclaw-hilt-demo

Connectors without native ask

ZeptoClaw, Codex, Hermes, Gemini CLI, Windsurf, OpenHands, and OpenCode cannot pause for a DefenseClaw approval on their documented hook surfaces. Their integrations apply an explicit connector-specific fallback—typically alert, allow, or injected context—and keep raw_action: "confirm" available for audit.

defenseclaw tui

The TUI is useful for reviewing audit events, alerts, logs, and inventory. It does not expose a pending-approval queue that can resume those connector calls. If a workflow requires approval before execution, use a native-ask connector/event or make the policy action an unconditional block.

A confirmable finding pauses only on an event with native ask support. All other events take their connector-specific fallback immediately.

When HITL is not the right answer

If nearly every tool call asks for approval, tune the policy instead of training operators to click through. If required actions never pause, first confirm that the finding reaches --hilt-min-severity and that the exact connector event supports native ask.

HITL reference

The per-connector event matrix, thresholds, and decision flow.

Changing connectors

Add or reconfigure connector wiring without losing audit history.