feat(agents,tools)!: SP-3 native human-in-the-loop tool approval

[ancongui]

Summary

SP-3 from the pydantic-ai modernization roadmap: re-base tool approval / human-in-the-loop onto pydantic-ai's native deferred-tools protocol, replacing the bespoke ApprovalGuard.

A tool marked requires_approval=True makes the agent run pause before executing it and return a DeferredToolRequests as result.output (detect with is_deferred(result)). The caller resumes with the human's decision:

result = await agent.run("Delete record 42.")
if is_deferred(result):
    approvals = {c.tool_call_id: True for c in result.output.approvals}  # True / ToolApproved(override_args=…) / ToolDenied(message=…)
    result = await agent.run(message_history=result.all_messages(),
                             deferred_tool_results=DeferredToolResults(approvals=approvals))

FireflyAgent auto-detects HITL (any approval-requiring tool / ToolKit / as_toolset(), or an ApprovalRequiredToolset) and widens its output union to allow the pause only then — non-HITL agents are unchanged. hitl=True forces it (e.g. for tools that defer dynamically by raising ApprovalRequired); approval_handler= resolves approvals inline (no pause) via a native HandleDeferredToolCalls capability.

Design

• Three distinct HITL layers, kept separate by design: tool approval (native deferred-tools, agent layer — this PR), workflow human() / WorkflowInterrupt (journal-replay), pipeline Pause / approve_pause (checkpoint). Built after an Understand-workflow mapped all four current HITL surfaces against the native protocol.
• Post-run cross-cutting code (memory persist, output-guard, validation, cache, logging, explainability) skips a paused DeferredToolRequests output — it is a control object, not a final answer.
• Guard denials now raise ToolGuardError (a ToolError subclass — existing except ToolError unaffected).
• Bug fix (caught by the edge-case tests): _guarded_execute now lets ApprovalRequired/CallDeferred propagate untouched (like ModelRetry), so a tool that defers dynamically from its body actually pauses instead of being wrapped in ToolError.

Breaking

• ApprovalGuard + ApprovalCallback removed — replaced by the native protocol. Migration: docs/migration.md §6.

Tests & verification

• 25 unit tests in test_hitl_deferred.py (pause/resume, deny, override_args, metadata round-trip, dynamic ApprovalRequired, ApprovalRequiredToolset e2e, multi-approval, inline handler None/resolve, middleware/memory skips, detection) + 6 in test_requires_approval.py.
• 1486 PR-gate tests, ruff + ruff format clean, pyright 0 errors.
• Live Anthropic e2e 10/10, including a real-model pause→approve→resume; plus ephemeral live checks of override_args, and dynamic ApprovalRequired approve + deny.

Docs

• New "Human-in-the-Loop Tool Approval" sections in docs/tools.md (with a pause→approve→resume sequence diagram) and docs/agents.md; tutorial.md, architecture.md, migration.md updated; README Feature Highlights / Module Reference / Quick Start updated (drop ApprovalGuard, add HITL + SP-5 output modes); stale diagram/claims fixed.
• Version 26.06.11, CHANGELOG.md + uv.lock updated.