Agent Architecture Review, Snapshot di validazione

Design for delegation rather than direct manipulation

Delegation is modeled explicitly through `Policy`, `create_run()`, `draft_tasks()`, and `execute_approved_payments()`: the user sets constraints such as caps, allowlists, due windows, and required approver role, while the workflow classifies invoices and executes only within that delegated scope. Authority is bounded by `policy_hash`, `invoice_snapshot_hash`, and per-task statuses rather than hidden prompt-like behavior.

Ensure that background work remains perceptible

Background work remains perceptible through durable `RunLedger` events, `DurableOperatorInbox` alerts, `RunStatus` / `TaskStatus`, and `inspect_run()`, which exposes current status, task counts, critical alerts, reconciliation needs, and audit-chain health. `replay_run_from_ledger()` preserves continuity after process interruption and promotes unresolved submitted tasks to `SUBMITTED_UNKNOWN`.

Align feedback with the user’s level of attention

Feedback is calibrated by separating routine audit events from attention-demanding inbox alerts: normal transitions are appended to `RunLedger`, while failures, forged approvals, insufficient roles, unfinished tasks, and reconciliation problems are posted via `DurableOperatorInbox.post()` with warning or critical severity. `inspect_run()` surfaces only `critical_alerts` in the primary view while retaining detailed events for inspection.

Apply progressive disclosure to system agency

The primary inspection surface in `inspect_run()` gives a concise summary first: run status, policy hash, cancellation/pause state, audit-chain integrity, critical alerts, status counts, submitted amount, and reconciliation count. Deeper detail remains available through the per-task list and the ledger’s `read_run_events()` / `verify_chain()` paths, so agency is disclosed progressively rather than as an opaque black box or raw log dump only.

Replace implied magic with clear mental models

The code uses explicit mental-model primitives: `RunStatus` distinguishes pending, drafting, awaiting approval, paused, executing, completed, partial, cancelled, and failed; `TaskStatus` distinguishes awaiting approval, approved, submitted, submitted unknown, succeeded, failed, skipped, and cancelled. `classify_invoice()` records concrete `policy_decision` reasons, and `ApprovalEnvelope` makes clear that payment execution requires a signed authorization bound to run, task, policy, invoice snapshot, role, and expiry.

Expose meaningful operational state, not internal complexity

Operational state is exposed in user-relevant terms through `inspect_run()` fields such as `status`, `critical_alerts`, `summary.by_status`, `submitted_amount_pence`, and `needs_reconciliation`. Low-level mechanics like the hash chain remain available as `audit_chain_intact` / `audit_chain_first_divergence_event_id` and ledger events, while the primary status model stays oriented around approval, execution, blocking, reconciliation, and completion.

Establish trust through inspectability

Inspectability is supported by architectural primitives rather than wrappers: `RunLedger` writes append-only JSONL events, `_hash_event_body()` creates a per-run hash chain, `verify_chain()` detects tampering, and `replay_run_from_ledger()` reconstructs state. Decisions and actions are traceable via `policy_hash`, invoice `snapshot_hash()`, approval envelope signatures, bank responses, transfer IDs, task status transitions, and actor IDs in audit events.

Make hand-offs, approvals, and blockers explicit

Approvals and blockers are explicit and load-bearing: `approve()` verifies the HMAC-signed `ApprovalEnvelope`, expiry, policy hash, invoice snapshot hash, task status, terminal-run state, and required approver role before setting `TaskStatus.APPROVED`. Execution blockers are surfaced through inbox alerts for forged envelopes, expired or insufficient approvals, policy violations, bank failures, unfinished tasks, and `SUBMITTED_UNKNOWN`; the iteration-6 whole-projection counts (`failed_total`, `succeeded_total`, `actionable_total`) prevent `COMPLETED` while any failed or actionable task remains.

Represent delegated work as a system, not merely as a conversation

Delegated work is represented as a structured system using `PaymentRun`, `PaymentTask`, `AuditEvent`, `RunLedger`, and `DurableOperatorInbox`, all keyed by `run_id` and `task_id`. The workflow separates execution state from narrative output and supports multi-step dependencies across drafting, approval, submission, reconciliation, retry, pause, cancel, and terminal resolution.

Optimise for steering, not only initiating

The workflow supports steering after initiation through `pause_run()`, `resume_run()`, `cancel_run()`, `retry_failed_task()`, `resume_after_failure()`, and `reconcile_submitted_task()`. Most importantly, `execute_approved_payments()` checks `ledger.latest_steering_intent(run_id)` before each external submit, so pause or cancellation requests recorded in the ledger can interrupt execution before additional bank calls are made.