# 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.