D1 · Agentic Architecture › Cluster 3 · Tool Use

3.6 · Human-in-the-Loop / Approval Gates

Intercept the tool_use before it runs — approve, deny, adapt

CONCEPT The gate lives between request and execution

Claude only requests a tool; your code decides whether to run it. That gap — after the tool_use block, before you execute — is exactly where a human-in-the-loop gate belongs. For side-effecting or irreversible actions (payments, deletes, emails, deploys), you pause, ask a human, and only then run the tool or refuse it.

OutcomeWhat your code doesWhat Claude sees back
ApproveRun the tool, capture outputA normal tool_result with the output
DenySkip executionA tool_result explaining the denial (optionally is_error: true) so Claude adapts
Auto-allowRead-only / safe tool → run without askingNormal tool_result
🔑 A gate requires the manual loop (3.5), not the Tool Runner — you must sit between the tool_use and its execution. On denial, you still return a tool_result for that tool_use_id (the 3.2 contract doesn't relax): a message like "denied by operator" lets Claude choose another path instead of hanging.
Gate on the action's blast radius, not on model confidence. Side-effecting / irreversible tools (write, delete, pay, send, deploy) get a gate; pure reads can auto-allow. This is the operational half of tool safety — cross-reference 5.4 (least-privilege / dangerous tools).

DIAGRAM The approval gate flow

flowchart TD A([tool_use block]) --> B{Side-effecting /
irreversible?} B -->|No · read-only| R[run tool] B -->|Yes| G{Human approves?} G -->|Approve| R G -->|Deny| D["tool_result:
'denied' (is_error)"] R --> RES["tool_result: output"] RES --> L([append · loop]) D --> L classDef safe fill:#d4edda,stroke:#28a745,color:#155724; classDef gate fill:#fff3cd,stroke:#ffc107,color:#856404; classDef deny fill:#f8d7da,stroke:#dc3545,color:#721c24; class R,RES safe; class G gate; class D deny;

CODE An approval gate around tool execution

Manual loop: classify each tool_use, require approval for dangerous ones, and always return a matching tool_result — even on denial.

DANGEROUS = {"send_payment", "delete_record", "send_email"}

messages = [{"role": "user", "content": user_request}]
while True:
    resp = client.messages.create(model="claude-opus-4-8", max_tokens=1024,
                                  tools=TOOLS, messages=messages)
    if resp.stop_reason != "tool_use":
        break
    messages.append({"role": "assistant", "content": resp.content})

    results = []
    for tu in [b for b in resp.content if b.type == "tool_use"]:
        # --- THE GATE: intercept BEFORE executing ---
        if tu.name in DANGEROUS and not human_approves(tu.name, tu.input):
            results.append({
                "type": "tool_result",
                "tool_use_id": tu.id,        # still MUST answer the id
                "content": "Denied by operator: action not approved. "
                           "Propose a safer alternative or ask the user.",
                "is_error": True,           # Claude adapts instead of assuming success
            })
            continue
        # approved (or safe/read-only) → actually run it
        out = run_tool(tu.name, tu.input)
        results.append({"type": "tool_result",
                        "tool_use_id": tu.id, "content": out})

    messages.append({"role": "user", "content": results})
Because denial returns a real tool_result (not silence), Claude stays in a valid conversation and can re-plan — e.g. ask the user for confirmation or pick a non-destructive tool.

EXAM TRAPS

Trap: On denial, sending nothing back. → You must still return a tool_result for that tool_use_id (an explanatory message, often is_error: true). Silence breaks the 3.2 contract and Claude can't adapt.
Trap: Trying to gate with the Tool Runner. → The Runner executes tools for you; approval gates need the manual loop so you can intercept before execution (3.5).
Trap: Relying on prompt instructions ("don't delete without asking") as the safety control. → Prompts are advisory; the enforceable gate is in your code, at the execution boundary.
Trap: Gating everything, including reads. → Auto-allow safe read-only tools; reserve gates for side-effecting / irreversible actions or you add latency and approval fatigue for no safety gain.

PRACTICE

Q1 · Where in the loop does the approval check go, and why there?

Between receiving the tool_use block and calling run_tool. That's the only point where you can still refuse before the side effect happens — Claude has only requested the action, not performed it.

Q2 · A human denies a send_payment call. What exactly goes back to Claude?

A tool_result with the matching tool_use_id, an explanatory content ("denied…"), and typically "is_error": true. That keeps the contract valid and lets Claude propose an alternative instead of assuming the payment succeeded.

Q3 · Which tools deserve a gate, and which should auto-allow?

Gate side-effecting / irreversible tools (pay, delete, send, deploy). Auto-allow pure read-only tools. Gate by blast radius, not by model confidence — this pairs with least-privilege design in 5.4.