Agent Architecture Review, Validation snapshot

Design for delegation rather than direct manipulation

Delegation is expressed through `GovernedPolicy` fields such as `task`, `instructions`, `max_turns`, `timeout_seconds`, `permitted_action_scope`, and `approval_gates`. Execution is only started through `start_governed_run` / `run_governed`, and the package exposes `pause_run`, `resume_run`, and `abort_run` as explicit controls rather than requiring users to manually perform each browser/form action.

Ensure that background work remains perceptible

Background work remains perceptible through the durable `runs` table, hash-chained `events`, immediate `run_id` creation in `start_governed_run`, and read-side `status()` / `timeline()` functions. `GovernedRunHooks._checkpoint` emits `heartbeat` events according to `policy.heartbeat_every_n_turns`, preserving continuity across sessions via SQLite.

Align feedback with the user’s level of attention

Feedback is calibrated by channel: `status()` returns a concise current state and latest message, `timeline()` exposes detailed event history, and CLI `_stream_attention_required` escalates only attention-worthy states such as `AWAITING_APPROVAL`, `PAUSED`, `FAILED`, and `TIMED_OUT`. Routine progress is represented by heartbeat events rather than constant foreground interruption.

Apply progressive disclosure to system agency

The observability surface uses progressive disclosure: `RunStatus` exposes the primary state, terminal flag, latest message, final output, and failure reason, while `timeline()` provides detailed per-event inspection and `verify_audit()` provides deeper integrity verification. This cleanly separates summary status from diagnostic history.

Replace implied magic with clear mental models

The code replaces implied magic with explicit operating rules: `RunState` defines a closed lifecycle, `VALID_TRANSITIONS` defines legal state movement, `GovernedPolicy._require_unconditional_approval_for_submission_capable_scope` refuses submission-capable actions without unconditional approval gates, and `_build_governed_agent` sets `handoffs=[]` while `GovernedRunHooks.on_handoff` fails explicitly if a handoff occurs.

Expose meaningful operational state, not internal complexity

Operational state is exposed through user-relevant states such as `initialised`, `in_progress`, `awaiting_approval`, `paused`, `complete`, `failed`, `aborted_by_user`, and `timed_out`. `status()` reports these states and the latest actionable message, while lower-level hashes, event data, and diagnostics are reserved for `timeline()` and `verify_audit()`.

Establish trust through inspectability

Inspectability is backed by a concrete audit primitive: `append_event` creates a per-run hash chain using `prev_hash` and `entry_hash`, `run_genesis` commits the canonical policy digest, tool dispatch logs `tool_call_started`, `tool_call_completed`, and `tool_call_failed`, and `verify_audit()` recomputes the chain and reconciles terminal `final_output` / `failure_reason` commitments against the `runs` row.

Make hand-offs, approvals, and blockers explicit

Approvals and blockers are explicit. `wait_for_decision` transitions the run to `RunState.AWAITING_APPROVAL`, records the matched `rule_ids`, `rule_descriptions`, `action_payload`, and `action_digest`, then blocks until `resume` or `abort`. Scope violations, unsupported handoffs, approval binding mismatches, timeouts, and aborts all transition to explicit terminal or blocked states with recorded reasons.

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

Delegated work is represented as a structured system rather than a chat transcript: there is a persistent `runs` record, an `events` timeline, a `steering_commands` control plane, a closed `RunState` graph, and a single governed tool dispatcher. `agent.py` centralises the only `Runner.run` call site and separates execution state from conversational/model output.

Optimise for steering, not only initiating

The system supports steering after initiation through durable `abort_run`, `pause_run`, and `resume_run` commands stored in `steering_commands`. `GovernedRunHooks._drain_steering` checks commands at agent/tool boundaries, prioritises aborts in `claim_next_steering_command`, moves paused runs to `RunState.PAUSED`, waits for resume or abort, and approval gates require operator resume before executing submission-capable actions.