Agent Architecture Review, Snapshot di validazione

The delegated authority envelope is explicit in GovernedPolicy: task, instructions, max_turns, timeout_seconds, permitted_action_scope, and approval_gates. start_governed_run rejects free-form dicts, constructs the Agent and governed tool list internally, and exposes only an ActionExecutor that is called after GovernedActionDispatcher enforces scope, approval, and audit.

Foreground attention is now calibrated by _stream_attention_required polling timeline(run_id) and escalating only state_transition events in AWAITING_APPROVAL, PAUSED, FAILED, TIMED_OUT, or ABORTED_BY_USER. Deduplication is keyed by (kind, seq), so repeated approval blockers are surfaced instead of being swallowed by state-level deduplication. Delta: this directly addresses the prior feedback-alignment issue.

The read model applies progressive disclosure: status(run_id) returns concise state, latest_message, final_output/failure digests, and terminality; timeline(run_id) returns the redacted event ledger; evidence(run_id) is a separate raw-payload surface; verify_audit(run_id) is an explicit diagnostic integrity check.

The system presents a clear mental model through typed constraints and documented behaviour: GovernedPolicy is frozen, permitted_action_scope is explicit, SUBMISSION_CAPABLE_ACTIONS require unconditional ApprovalGateRule coverage, build_governed_tools exposes a single perform_action tool with permitted actions in its description, and CLI run creates approval gates rather than offering a disable-approval flag.

Operational state is exposed through a closed RunState enum with user-relevant values such as IN_PROGRESS, AWAITING_APPROVAL, PAUSED, COMPLETE, FAILED, ABORTED_BY_USER, and TIMED_OUT. transition enforces VALID_TRANSITIONS, terminal states are absorbing, and RunStatus returns state/is_terminal/latest_message rather than leaking low-level loop internals.

Approval and blocker states are explicit. GovernedPolicy._require_unconditional_approval_for_submission_capable_scope rejects submission-capable actions without always-on approval rules. wait_for_decision transitions to AWAITING_APPROVAL, records action_digest/rule_ids, heartbeats while waiting, and proceeds only on resume or aborts on abort. GovernedActionDispatcher recomputes the action digest before execution, and GovernedRunHooks.on_handoff transitions to FAILED for unsupported handoffs.

Delegated work is represented as a structured system rather than a chat transcript: runs holds lifecycle state, events is an append-only hash-chained timeline, evidence segregates raw payloads, steering_commands is a durable control plane, run_lease_history records lease events, and observability exposes status/timeline/evidence/verify_audit surfaces.

The code supports mid-run steering through durable abort_run, pause_run, and resume_run commands, which are consumed at hook checkpoints and during approval waits. Policy mutation is deliberately disallowed through frozen Pydantic models and the _drive_agent_loop digest check; the documented correction model is abort/restart rather than live policy rewrite. Delta: this addresses the prior steering finding by adding an explicit immutability contract plus audited pause/resume/abort primitives.