docs/PR_0.2.2.md

security: add optional HOL Guard enforcement to RuntimeDispatcher

Motivation

External runtime review identified RuntimeDispatcher as the correct enforcement seam and requested a regression proving that denial of a mutating call has zero side effects.

Architecture

This change adds a small Trace2MCP-owned asynchronous RuntimeGuard protocol. Existing contract, integrity, policy, approval, binding, and schema checks remain authoritative. The optional guard runs after those checks and immediately before the exact bound handler. HOL Guard is integrated through its supported CLI hook instead of private Python modules.

Security properties

• Guard denial and review-required decisions invoke no handler.
• Configured guard errors, timeouts, malformed output, and unknown actions fail closed.
• Trusted reviewed contracts, not trace metadata, supply security classification.
• Direct, nested, and indirect managed invocations traverse the same guard.
• Guard requests use immutable argument snapshots.
• Generated projects remain locked until contracts are reviewed.

Tests

The adversarial suite covers allow, deny with zero effects, internal-denial precedence, metadata downgrade, nested and indirect calls, approval requests, guard exceptions, immutable arguments, response normalization, and unavailable executable behavior. A real isolated HOL Guard smoke blocks a destructive shell-shaped request before any handler call. See READY_TO_PUBLISH.md for final exact counts and artifact hashes.

Compatibility

Core pip install trace2mcp remains dependency-free. HOL Guard is disabled unless TRACE2MCP_HOL_GUARD_EXECUTABLE is set. It is installed separately because its current MCP v1 requirement conflicts with Trace2MCP's MCP v2 extra. Compilation and frozen replay are unchanged and do not call the guard.

Trust boundary

This mediates Trace2MCP-managed capabilities; it does not sandbox arbitrary Python inside an authorized handler. Untrusted handlers still require OS-enforced isolation.

Reviewer note

Please focus review on:

• src/trace2mcp/runtime.py: final authorization/invocation ordering;
• src/trace2mcp/runtime_guard.py: generic request and decision contract;
• src/trace2mcp/hol_guard.py: CLI protocol, action normalization, failure handling;
• tests/test_runtime_guard.py: zero-side-effect and alternate-route regressions;
• src/trace2mcp/codegen.py: generated-server opt-in wiring.

Runtime integration direction was inspired by review feedback from @kantorcodes1 / HOL Guard. This change does not claim endorsement or certification.