feat: surface MCP Gateway integrity filtering and guard policy events in gh aw audit

[Mossaka]

Summary

gh aw audit should surface integrity filtering and guard policy events from the MCP Gateway, giving workflow authors visibility into when and why tool calls are blocked or scoped by guard policies.

This is not covered by #22757 — that issue focuses on MCP tool call stats, session metrics, token usage, and safe-output compliance. Guard policy enforcement (integrity filtering, repo scoping) is a separate dimension of observability.

What are guard policies?

Guard policies are defined in workflow frontmatter under tools: github: and control which tool calls the MCP Gateway allows:

tools:
  github:
    mode: remote
    toolsets: [default]
    repos: "public"              # or "all", ["owner/repo", "owner/*"]
    min-integrity: reader        # one of: none, reader, writer, merged

• repos — Scopes which repositories a tool can access (exact match, owner wildcard, prefix wildcard)
• min-integrity — Minimum DIFC integrity level required for a tool call to proceed
• Both fields are required together (validated in pkg/workflow/tools_validation.go:61-200)

See full spec: scratchpad/guard-policies-specification.md

What events are produced?

When a guard policy blocks or filters a tool call, the MCP Gateway logs these decisions. Currently:

• gateway.jsonl records tool calls with type: "tool_call", status, duration, and errors — but does NOT explicitly tag integrity-filtered events
• filtered_integrity parameter in pkg/cli/mcp_tools_privileged.go can filter log runs to those containing integrity-filtered events
• Daily analysis workflow (.github/workflows/daily-integrity-analysis.md) does Python-based bucketing of integrity-filtered events

The gap: gh aw audit does not parse or surface any of this.

Proposed metrics for gh aw audit

Guard Policy Summary

• Total tool calls subject to guard policies
• Tool calls blocked by min-integrity (with integrity level distribution)
• Tool calls blocked by repos scope (with repo pattern details)
• Tool calls allowed through guard policies

Per-Server Breakdown

• Which MCP servers had guard policies applied
• Block rate per server
• Most frequently blocked tools

Integrity Level Distribution

• Count of tool calls at each integrity level (none, reader, writer, merged)
• Which levels triggered filtering

Debugging Support

• When a tool call fails, show whether it was blocked by a guard policy vs. a runtime error
• Surface the specific guard policy rule that caused the block
• This directly helps debug "why did my agent fail to call this tool?" scenarios

Key files

File	Purpose
pkg/workflow/tools_types.go:265-302	GitHubIntegrityLevel, GitHubReposScope, GitHubToolConfig with guard policy fields
pkg/workflow/tools_validation.go:61-200	validateGitHubGuardPolicy() — repos + min-integrity validation
pkg/workflow/tools_parser.go	Extracts repos and min-integrity from frontmatter
pkg/cli/gateway_logs.go	parseGatewayLogs(), GatewayMetrics — current parsing (no guard policy events)
pkg/cli/mcp_tools_privileged.go	filtered_integrity parameter for log filtering
scratchpad/guard-policies-specification.md	Full guard policies design spec

Tasks

• Define structured log event types for guard policy decisions in gateway.jsonl (e.g., type: "guard_policy", action: "blocked"/"allowed", reason: "min_integrity"/"repo_scope")
• Emit guard policy events from the MCP Gateway when tool calls are filtered
• Extend GatewayLogEntry and GatewayMetrics in gateway_logs.go to parse guard policy events
• Add guard policy summary section to gh aw audit output (blocked/allowed counts, integrity level distribution)
• Add per-server guard policy breakdown
• Surface guard policy blocks in tool call error context (debugging)
• Add unit tests for guard policy log parsing
• Update LOGGING.md with guard policy event documentation

Relationship to other issues

• Parent epic: Epic: audit #22735 (audit/observability)
• Sibling: feat: expand gh aw audit with MCP, session, token, safe-output, and agent performance metrics #22757 (MCP tool stats, session metrics, token usage — does NOT cover guard policies)
• Related: Daily integrity analysis workflow already does offline analysis; this brings it into gh aw audit

🤖 Generated with Claude Code

[Mossaka]

Integrity filtering events are logged in rpc-messages.jsonl, not gateway.jsonl.

rpc-messages.jsonl contains raw JSON-RPC protocol messages between the AI engine and MCP servers (see RPCMessageEntry struct in gateway_logs.go:88). Each entry has timestamp, direction (IN/OUT), type (REQUEST/RESPONSE), server_id, and a payload with the full JSON-RPC message.

Guard policy enforcement decisions (tool call blocked/allowed due to integrity level or repo scope) would appear as error responses in this file. The current parseRPCMessages() parser only tracks tools/call methods for duration/count metrics — it does NOT extract guard policy blocks or integrity filtering events.

Updated implementation approach: Parse rpc-messages.jsonl for error responses that indicate guard policy violations (likely specific JSON-RPC error codes or messages), rather than adding new event types to gateway.jsonl.