feat(hitl): interactive mode + scoped_mcp_hitl_confirm tool

[TadMSTR]

Summary

Adds hitl.mode: enforce | interactive to scoped-mcp manifests. Default is enforce — no behavior change for any manifest that doesn't opt in.

interactive mode fires the same Matrix notify and the same immediate reject (the agent still stops and asks), but resolves the pending request in-session via a new companion tool scoped_mcp_hitl_confirm(approval_id, decision) that the agent calls directly — replacing the token-expensive "read the Matrix message and self-resolve via a system-ops shell call" workaround. It reuses the shared hitl_endpoint.approve/deny logic (no duplicated approval path).

Build: scoped-mcp-hitl-bypass-mode-2026-07. Does not touch Vikunja #203 (the broken enforce-mode bot→endpoint path — deferred, out of scope).

Changes

• manifest.py — new HitlConfig.mode enum (enforce/interactive, default enforce).
• registry.py — _register_hitl_confirm_tool; registered only when hitl.mode == interactive AND the agent actually gates tools AND a state backend exists. An enforce-mode / unattended agent never gets the tool, so it can't self-resolve a headless run's gated calls.
• hitl_endpoint.py / hitl_http.py / registry_db.py — thread a resolved_via audit tag (matrix_bot | courier | interactive_self_service) so the in-session shortcut is always distinguishable from the real out-of-band paths. Written only when supplied, so a later consume/expire transition never clobbers the approve-time channel.
• migrations/0002_hitl_resolved_via.sql — ADD COLUMN IF NOT EXISTS resolved_via (fail-open until applied; safe to run before the code).
• docs/manifest-schema.md — documents mode + the interactive trust tradeoff.

Trust tradeoff (interactive only, by design)

scoped_mcp_hitl_confirm trusts the agent's own report that the operator approved in the current conversation turn — the same trust level every other interactive tool call already runs under. It is registered only for interactive-mode agents, so enforce-mode (unattended) agents can never reach it. The agent-facing contract ("only after an explicit in-conversation approve/deny") lives in the tool docstring, docs/manifest-schema.md, and the developer/sysadmin CLAUDE.md.

Tests

• test_hitl_interactive.py (new) — registration gating (present for interactive, absent for enforce/default/no-approval), approve/deny behavior via the FastMCP client, invalid decision, cross-agent isolation, resolved_via tagging.
• test_manifest.py — mode default/accept/reject.
• test_registry_db.py — resolved_via SQL param positioning (guarded + unguarded), and that it's omitted when not supplied.

Full suite: 737 passed, 11 skipped (Dragonfly/Postgres/otel-gated). ruff check + ruff format --check clean.

Deploy note

Venv upgrade to this release must land before the companion manifest flip (host-forge-scripts) — HitlConfig(extra="forbid") rejects the mode field on older builds. Apply 0002_hitl_resolved_via.sql to agent-postgres as part of deploy.

🤖 Generated with Claude Code