RFC: Event-Driven Governance and Actions

[krokoko]

Primary area: Cross-cutting / multiple

Related issue or feature request: (none — new proposal)

---

Summary

Today, human-in-the-loop (HITL) and most governance controls are synchronous and tool-centric: Cedar policies in PreToolUse gate Bash, Write, Read, etc. Operators configure bash patterns and tool shapes — not semantic moments like "plan ready", "PR opened", or "cumulative cost exceeded $25".

Meanwhile, observability and notifications are already event-driven via TaskEventsTable and FanOutConsumer, but that plane cannot prevent side effects unless something blocked earlier on the hot path.

This RFC proposes a unified Event Governance layer: a normative event catalog, declarative event rules (condition → action), sync (in-agent, can block) vs async (stream consumer, react only) evaluation modes, registry-native configuration (versioned event-rule-pack assets pinned by blueprints), and UX as a first-class requirement (bgagent submit governance preview, unified bgagent pending for event- and tool-sourced approvals). Tool-level Cedar HITL remains the fail-closed safety net for execution.

Use case and motivation

Who it's for: platform engineers, blueprint authors, security reviewers, and operators using bgagent, Slack, and GitHub fan-out.

Pain today:

Need	Today	Gap
Approve plan before code runs	Awkward Cedar on Write/Bash	Same intent reachable via many tool sequences
Pause at cumulative cost threshold	Tool-centric only	No aggregate rules on agent_cost_update
Notify on pr_created on protected branch	Fan-out filters	Cannot gate before PR without sync checkpoint
Escalate on high-severity approval_requested	Partial fan-out	Not unified with rule packs / audit

Expressing lifecycle governance as Cedar on tool argv is unreliable (retry/model variation, approval fatigue, false positives). Reactive needs (notify, audit, post-hoc cancel) do not belong on the tool hot path.

After this RFC: Operators configure governance against named lifecycle moments (checkpoints, milestones, aggregates). Sync checkpoints block irreversible work; async rules notify, escalate, or cancel without pretending they prevented an action that already happened.

Proposal

Core design:

Two planes, one catalog

1. Normative event catalog — stable names/schemas for lifecycle, execution, milestone, checkpoint, and policy events (JSON Schema, additive versioning).
2. Event rules — on event + when conditions → actions: require_approval, notify, escalate, cancel_task, inject_nudge, observe_only.
3. Sync evaluation — in-agent at checkpoints (checkpoint:before_execution, before_open_pr, etc.); same latency class as Cedar; can transition to AWAITING_APPROVAL.
4. Async evaluation — TaskEventsTable stream consumer for notify, aggregates (agent_cost_update cost ceiling), post-hoc cancel; tens–hundreds of ms; must not imply blocking unless UX is explicit.
5. Precedence: tool Cedar hard-deny always wins; async never overrides sync deny; composable with existing TaskApprovalsTable / bgagent approve / deny.

Capability registry (configuration home)

Asset type	Consumed by
cedar-policy-module	Agent PolicyEngine
event-rule-pack	Sync evaluator + async consumer
notification-profile	Fan-out / event consumer
checkpoint-catalog	Agent pipeline + Change Manifest L1

Blueprints pin semver assets instead of inlining fragile YAML. Interim: inline eventRules until registry MVP (Phase 3).

UX (before → after)

Before: bgagent pending shows bash argv; submitters surprised by mid-run tool gates.

After:

• Submit: governance preview from resolved registry pins (estimated interactive gates, rules that may fire).
• Watch: human-readable moments (Plan verified — awaiting your approval).
• Pending: unified queue — event-sourced and tool-sourced approvals differ in trigger context, not approve/deny mechanics.
• Authoring: bgagent registry list, bgagent rules eval --fixture, observe→enforce rollout per pack.

Phased delivery

Phase	Scope	Outcome
0	Catalog + observe_only + PolicyDecisionEvent	"Would have fired" in watch stream
1	Async notify/fan-out + webhook	Ping on PR/cost without new HITL
2	Sync checkpoints + manifest	Plan review before code (primary UX win)
3	Registry-native event-rule-pack	Org-wide versioned policy rollout
4	Advanced aggregates + async cancel	Operator automation

Phases 0–2 can ship with inline blueprint config; Phase 3 aligns with agent asset registry MVP.

Data model extensions

• TaskApprovalsTable: source (tool|event), event_id, checkpoint, rule_pack_id, rule_id.
• TaskEventsTable: catalog event types; optional correlation_id for dedupe.
• PolicyDecisionEvent (roadmap): unified audit for every evaluation.

Cross-links: CEDAR_HITL_GATES.md, CHANGE_MANIFEST.md, ORCHESTRATOR.md, Roadmap — Agent asset registry & Centralized policy framework.

Out of scope

• Replacing tool Cedar with event rules — fail-closed execution safety stays on PreToolUse.
• Stream-only HITL — async consumer alone cannot block fast agents (race).
• Inline blueprint YAML as the long-term config model — bootstrap only until registry ships.
• EventBridge as the primary internal bus — complementary export; TaskEventsTable remains source of truth for task-scoped ordering (initially).
• Full registry MVP in Phase 0–2 (designed for; not required to land catalog + observe + sync checkpoints).
• Raw JSONPath/Cedar in default operator UX — verbose mode only.
• Separate approve commands for event vs tool gates.

Potential challenges

Risk	Mitigation
Sync vs async confusion	Explicit modes in rule schema; UX copy for reactive approvals
Third DDB stream consumer capacity	Plan Kinesis migration; do not multiply consumers blindly
Overlapping tool + event require_approval	Scope algebra TBD; idempotency key (task_id, rule_id, correlation_id)
Async require_approval after pr_created	UX must state PR already exists — cannot un-create
Evaluator down	Sync blocking rules fail-closed; async notify may degrade with telemetry
Registry not ready	Inline blueprint eventRules + migration to pins
Checkpoint trust model	Mandatory pipeline hooks vs agent-declared milestones — open question
Rule language choice	Cedar-on-events vs CEL/JSONLogic — author persona TBD

Open questions (see RFC §12): rule language, scope algebra, checkpoint emission trust, third consumer design, Change Manifest state vs manifest_verified, multi-tenant registry merge order, observe→enforce granularity.

Dependencies and integrations

Component	Role
Agent (pipeline.py, runner.py, progress_writer.py, hooks)	Emit catalog events; sync checkpoint evaluation
CDK (fanout-task-events.ts, orchestrator, Blueprint construct)	Stream consumer; resolve registry pins at task start; extend fan-out
CLI (bgagent submit, watch, pending, future registry/rules eval)	Governance preview, unified pending UX
TaskEventsTable / TaskApprovalsTable	Event log + approval extensions
Agent asset registry (roadmap)	event-rule-pack, notification-profile assets
Centralized policy framework (roadmap)	PolicyDecisionEvent, observe/enforce modes

Related roadmap items: Agent asset registry, Centralized policy framework.

Alternative solutions

Alternative	Verdict
Extend Cedar only — synthetic action::Event types	Defer until event context schema stable; high author burden
Stream-only HITL in Lambda	Rejected for blocking — race with fast agents
Inline blueprint YAML forever	Bootstrap only; no versioning at scale
Replace tool Cedar with events	Rejected
EventBridge as primary bus	Complementary export; internal SoT stays TaskEventsTable

---

Note: Non-triaged RFCs may not get timely review. PRs on non-triaged issues might not be accepted.

• RFC PR:
• Approved by:
• Reviewed by:

[rpelevin]

This split between tool Cedar and event governance looks right. The invariant I would make explicit is that a sync event rule that can block execution needs to produce the same kind of durable decision object as a tool approval, not just a stream event plus UI pause.

For the RFC I would separate:

1. Event observation: catalog event id, schema version, task/run id, checkpoint, payload digest, and emitter identity.
2. Rule evaluation: rule_pack_id/version, rule_id, evaluation mode sync/async, inputs digest, and verdict.
3. Approval request: approval_id, source=event, event_id, rule evaluation id, expiry, reviewer context, and fail-closed timeout behavior.
4. Terminal decision: allowed/denied/expired/cancelled, decided_by, decided_at, reason, and the exact checkpoint/action digest it unlocks.

The important boundary is that async rules can create evidence, notifications, or post-hoc cancellation, but should not be represented as having prevented an action already past the checkpoint. Only sync checkpoints should produce a blocking AWAITING_APPROVAL state.

Acceptance tests I would add:

• a checkpoint:before_execution rule blocks before any Write/Bash/PR side effect;
• approval resumes only the same task id + checkpoint + event payload digest;
• changed manifest or changed rule-pack version invalidates the old approval;
• async pr_created approval is labeled reactive and cannot claim pre-action enforcement;
• overlapping tool and event approvals dedupe or chain through one correlation id;
• evaluator unavailable on a sync rule fails closed with an audit row.

That would keep event governance from becoming another notification stream and make the sync/async line operationally testable.

[krokoko]

Alignment with #99 item #4 (Blueprint phase tracking + PatternEvaluator)

Cross-posting design notes from a codebase review — this RFC is the right home for the semantic HITL work deferred from #99 when #248 / ADR-014 landed.

What #99 #4 proposed vs what shipped

AKW / #99 concept	Intent	Status in repo today
BlueprintTracker (macro)	Track pipeline execution phase	Done — workflow step runner (agent/src/workflow/runner.py) emits step:<name>:start / :complete milestones per WORKFLOWS.md
BlueprintTracker (micro, within run_agent)	Track agentic sub-phases (planning, coding, …)	Not built — this RFC's checkpoint catalog is the intended replacement
PatternEvaluator	Between turns, evaluate HITL patterns (conflicting evidence, low corpus quality, scope violation) → AWAITING_APPROVAL	Not built — dropped as AKW quality_checkpoints in ADR-014; tool-level Cedar REQUIRE_APPROVAL on PreToolUse shipped instead
Between-turns seam	Where PatternEvaluator would run	Exists — between_turns_hooks in agent/src/hooks.py (cancel → nudge → denial injection)

Recommendation: Do not resurrect BlueprintTracker / PatternEvaluator as separate modules. Fold into:

• Macro tracking → workflow runner (done)
• Micro tracking → thin ExecutionPhaseTracker inside pipeline.py / runner.py
• Pattern evaluation → sync event rule evaluator wired into between_turns_hooks and mandatory pipeline checkpoint emitters

Mapping to this RFC

#99 / AKW	#230 equivalent
BlueprintTracker (macro)	Workflow step runner + step:* catalog events
BlueprintTracker (micro)	Checkpoint catalog + mandatory pipeline hooks (checkpoint:plan_verified, checkpoint:before_open_pr)
PatternEvaluator	Sync event rule evaluator at between-turn / checkpoint seams
Inline blueprint HITL YAML	Inline eventRules on workflow YAML (bootstrap) → event-rule-pack registry pins (Phase 3)
PendingApproval + AWAITING_APPROVAL	Same pause surface; extend TaskApprovalsTable with source: 'event'

WORKFLOWS.md already states that full replacement of Cedar tool-level HITL with event rules is out of scope — correct. This RFC is additive: Cedar stays the fail-closed execution safety net; event rules express lifecycle governance Cedar cannot reliably express.

Phase 2 of this RFC delivers the primary UX win #99 #4 was aiming at (e.g. plan review before code).

Proposed RFC additions

1. Heritage / supersession (new section)

Supersedes AKW #99 item #4. Macro phases are realized by the workflow step runner (#248). Micro execution phases and semantic HITL patterns are realized by this RFC's checkpoint catalog + sync event rules — not by resurrecting quality_checkpoints / PatternEvaluator. Cross-ref: ADR-014, WORKFLOWS.md prior-art section.

2. Three governance planes (expand Summary)

Make explicit that operators configure three distinct reaction types:

Plane	Trigger	Outcome	Human action?
Execution deny	Cedar hard-deny / soft-deny on PreToolUse	DENY or AWAITING_APPROVAL	Approve/deny (soft-deny)
Governance pause	Catalog checkpoint + event rule	AWAITING_APPROVAL	Approve/deny
Environmental stop (#251)	Missing secret, egress deny, Cedar engine fail-closed	blocked event → fail fast	Operator fixes config, resubmits

Precedence: hard-deny > sync event deny > blocker fail-fast > async react-only.

3. Two-level phase model (new section)

Level	Owner	Examples	Trust for sync blocking
Workflow step	Step runner	hydrate_context, run_agent, ensure_pr	Platform-mandatory
Execution checkpoint	Pipeline inside run_agent	checkpoint:plan_verified, checkpoint:before_open_pr	Platform-mandatory; agent-declared milestones observe-only in Phase 0

Resolves open question checkpoint emission trust: sync require_approval rules bind only to platform-emitted checkpoints in Phase 2.

4. Evaluation seams (clarify Phase 2)

Wire sync evaluation at:

1. Mandatory pipeline hooks (before irreversible side effects)
2. between_turns_hooks (after each agent turn — the AKW PatternEvaluator seam)
3. Workflow step boundaries (optional: rules on step:ensure_pr:start)

Reinforce: sync blocking rules must not run only in the DDB stream consumer.

5. Workflow schema bootstrap (Phase 0–2)

Until registry MVP (#246), allow inline eventRules on workflow YAML (parallel to agent_config.cedar_policy_modules). Pin to event-rule-pack assets in Phase 3. Replaces AKW per-blueprint hitl_conditions without a permanent second config dialect.

6. Phasing tweak

Phase	#99 / #251 linkage
0	Catalog includes step:*, approval_requested, blocked (stub); observe_only on workflow steps
1	Async notify on pr_created, agent_cost_update
2	Delivers #99 #4 semantic HITL — sync checkpoint:plan_verified + require_approval
3	Registry event-rule-pack pins; supersedes inline eventRules
4	Async aggregates + cancel

7. Open questions

Add: Can a single between-turn moment fire both Cedar soft-deny and an event require_approval? (Idempotency key: (task_id, rule_id, correlation_id) — tie to approval_gate_cap.)

Resolve (lean): Phase 2 rule language = JSONLogic or CEL on catalog event payloads; defer Cedar-on-events until PolicyDecisionEvent schema stabilizes.

Implementation notes

1. Start Phase 0 with observe_only on existing step:* milestones — proves catalog + evaluator wiring with zero new pause behavior.
2. Phase 2 first blocking checkpoint: checkpoint:plan_verified before first Write/Bash in coding workflows.
3. Wire sync evaluator into between_turns_hooks — add _event_governance_between_turns_hook after cancel, before nudge.
4. Do not block on Mem0 / CapabilityIndex (Feature: Integrate AKW multi-agent capabilities into ABCA #99 Docs: user guide hard-codes us-east-1 #3, feat(compute): add ComputeStrategy interface with ECS Fargate backend #8) — semantic HITL rules can use turn/cost/artifact metadata without LTM.

Cross-link #251

See comment on #251 for the environmental blocker plane and how blocked catalog events integrate without opening the approval queue.

[rpelevin]

Agree with folding the phase-tracking and pattern-evaluator idea into the checkpoint catalog rather than reviving another module. The part I would make especially crisp is the trust boundary for blocking checkpoints.

If a sync rule can pause execution, I would make the checkpoint record say whether it was platform-emitted or agent-declared, and only allow the platform-emitted class to mint a blocking approval in the first enforcing phase. Agent-declared milestones can still be useful, but I would keep them observe-only until they are tied to a platform hook.

That gives a clean test matrix:

• platform emits checkpoint:plan_verified before first Write or Bash, sync rule matches, approval request is created with source=event, rule id/version, checkpoint event id, checkpoint payload digest, and target action or manifest digest;
• approval resume succeeds only for the same task id, checkpoint event id, rule evaluation id, rule-pack version, and target digest;
• agent emits a lookalike checkpoint name, evaluator records it as observe-only and cannot create a blocking approval;
• Cedar hard-deny and event require_approval fire on the same turn, hard-deny wins and no reusable approval is minted;
• environmental blocked event cannot be approved through the approval queue; it requires operator config repair and resubmission;
• sync evaluator unavailable at a mandatory checkpoint fails closed before Write/Bash/PR side effect and records the outage as an audit row;
• async PR-created or cost events are labeled reactive, and the UI cannot present them as pre-action prevention.

I would also make the idempotency key explicit for overlapping Cedar soft-deny and event pause. Something like task id plus checkpoint event id plus rule id plus correlation id would keep duplicate pauses from becoming duplicate authority.

That would make the three planes operationally distinct: execution denial, governance pause, and environmental stop all share an event catalog, but only the governance pause creates a resumable approval for a specific platform checkpoint.

[krokoko]

Starting implementation — drafting architecture + Phase 0 on branch feat/230-event-governance.