Agent Architecture Review, Snapshot di validazione

Delegation is represented as an explicit bounded-authority contract rather than free-form direct manipulation: `GovernedPolicy` captures `task`, `instructions`, `max_turns`, `timeout_seconds`, `permitted_action_scope`, and `approval_gates`; `start_governed_run` rejects non-`GovernedPolicy` inputs; `GovernedActionDispatcher.dispatch` enforces `policy.is_action_permitted(...)` before invoking the executor; and `ScopeViolation` terminates out-of-scope attempts. Users initiate work by assigning intent and constraints, while pause/resume/abort and approval gates govern execution.

Background execution is made perceptible through durable state and read-side surfaces: `create_run` inserts an `INITIALISED` row before the agent loop starts, `status(run_id)` exposes current state and latest message, `timeline(run_id)` exposes ordered events, `GovernedRunHooks._checkpoint` records heartbeat events, and `reap_stale_leases` transitions expired `INITIALISED`, `IN_PROGRESS`, `AWAITING_APPROVAL`, or `PAUSED` runs to `TIMED_OUT`. The run can be inspected after the initiating call returns because the run state is persisted in SQLite rather than only held in memory.

Feedback is calibrated by attention level: `status(...)` returns a concise `RunStatus` for lightweight monitoring; `timeline(...)` provides detailed event history only when requested; and the CLI `_stream_attention_required` emits only material attention states such as `AWAITING_APPROVAL`, `PAUSED`, `FAILED`, `TIMED_OUT`, and `ABORTED_BY_USER`, deduplicated by `(kind, seq)`. Routine heartbeats are kept in the timeline, while blockers and terminal states are escalated to stderr in the foreground run command.

The code uses progressive disclosure rather than dumping all internals into the primary surface. `status` exposes intent-relevant state, latest message, and terminal digests; `timeline` exposes the hash-chained operational ledger with sensitive fields redacted; `evidence` is a separate raw-payload sidecar; and `verify_audit` is an explicit diagnostic check. This cleanly separates summary, audit trail, and raw evidence access.

The mental model is explicit in code and runtime structures: `RunState` is a closed enum with states like `INITIALISED`, `IN_PROGRESS`, `AWAITING_APPROVAL`, `PAUSED`, and terminal outcomes; `GovernedPolicy` declares permitted actions and approval gates; `build_governed_tools` describes the single `perform_action` tool and its permitted action names; and `UnsupportedHandoff` makes handoffs unsupported rather than implicit. The package also documents the correction model as abort-and-restart rather than live policy mutation.

Operational state is exposed through meaningful lifecycle concepts instead of raw SDK internals. `RunStatus` surfaces `state`, `is_terminal`, `latest_message`, `final_output`, and `failure_reason`; `VALID_TRANSITIONS` constrains legal state movement; and CLI verbs map directly to user-relevant actions (`run`, `status`, `timeline`, `abort`, `pause`, `resume`, `reap`). Lower-level implementation details such as hash entries and evidence rows are reserved for `timeline`, `evidence`, and `verify_audit`.

Approvals, blockers, and handoffs are explicit. `GovernedPolicy._require_unconditional_approval_for_submission_capable_scope` rejects `click`, `submit`, or `keypress` authority unless an unconditional `ApprovalGateRule` covers the action; `wait_for_decision` transitions the run to `AWAITING_APPROVAL` and waits for `resume` or `abort`; approval is bound to `compute_action_digest`; and `GovernedRunHooks.on_handoff` transitions to `FAILED` through `UnsupportedHandoff` rather than allowing hidden delegation. Out-of-scope actions are recorded as `scope_violation` and fail the run.

Delegated work is represented as a structured system, not only as a chat transcript. Persistence is split across `runs`, `events`, `evidence`, `steering_commands`, and `run_lease_history`; execution state is governed by `RunState` and `VALID_TRANSITIONS`; the tool seam is centralized in `build_governed_tools`; and observability is provided through `status`, `timeline`, `evidence`, `verify_audit`, and `reap_stale_runs`. Conversation/model output is separated from run lifecycle, audit, evidence, and steering state.