design: GuardAgent output interception plane (PII, schema, rate-limit, content policy) #947

Summary

Design and prototype a platform-level output monitor that sits between agent completion events and their destinations (users, downstream agents, channels). Resolves target architecture open question #3: where the rule-based vs LLM-based evaluation boundary lives.

Context

docs/planning/TARGET_ARCHITECTURE.md §"GuardAgent" describes the destination capability — PII detection, output schema validation, external-call rate limiting, content policy enforcement — and §"Key Open Questions" #3 names the unresolved decision: rule-based (regex, schema) is implementable today; LLM-based semantic quality scoring is more powerful but adds latency and cost. The boundary between them must be designed before any GuardAgent ships.

GuardAgent intercepts at the event bus (#306) between agent completion and subscriber delivery, so it does not require changes to the agent runtime — but it does require a stable completion event contract, which Sprint D′ (#524 state machine) is still hardening.

Acceptance Criteria

• Design document under docs/planning/ (proposed: GUARDAGENT_DESIGN.md) covering:
  • Where in the event-bus pipeline GuardAgent intercepts (before fan-out vs after, ordering with feat: agent-authoritative execution state machine with single-writer projection (RELIABILITY-005) #524 projector)
  • Rule-based vs LLM-based evaluation split — which checks belong to which tier, and the latency/cost budget for each
  • Per-agent opt-in mechanism (template.yaml field? agent_ownership column?)
  • Blocking vs advisory mode — what happens when GuardAgent rejects an output (operator queue, quarantine, log-only)
  • Integration with feat: agent-reported structured reports via MCP + dashboard display #918 (agent-reported structured reports) if there's overlap
• Prototype the rule-based tier only (PII regex, schema validation against agent's declared output contract). Defer LLM tier to a follow-up issue.
• Demo: an agent emits an output containing a fake SSN; GuardAgent blocks delivery to external channel and pushes to operator queue.

Technical Notes

• This is post-Sprint-D′ work — depends on feat: agent-authoritative execution state machine with single-writer projection (RELIABILITY-005) #524 projector landing so completion events are canonical.
• Output schema validation needs an agent-side contract in template.yaml (output_schema: field). Define that schema in this issue or a sibling.
• Per target arch: opt-in per agent initially, opt-out for system agents.
• Rate limiting on external API calls initiated from agent outputs may need to live elsewhere — flag if so.

🤖 Generated with Claude Code