klbr plan v2 — what changed #

Date: September 6, 2026. Design revision only; no klbr runtime implementation or failure testing was performed.

Read this version #

implementation-plan.md is the integrated full plan. hooks-and-policy.md defines the detailed extension contract. behavior-contracts.md preserves the original source evidence unchanged.

The earlier plan suggested deferring a policy boundary and mainly making skills/settings editable. That is superseded: Python policy hooks are now a first-class requirement implemented before the replacement turn loop. Rust is a deliberate foundation for typed resource ownership, reliability engineering and efficient always-on execution, not merely a way to reuse an existing codebase.

Architecture #

One Rust daemon owns persistence, provider/transport execution, state transitions, resource limits, receipts, scheduling mechanisms and recovery. Python owns ordinary policies, skills and guidance. One persistent workbench per active agent session provides interactive computation. A supervised persistent hook-worker role evaluates published callbacks independently of that workbench, using the same Python runtime and transport. It is not another agent orchestrator.

The host exposes single-owner typed decision slots, ordered representation transforms and asynchronous post-commit observers. Meaningful hook families cover input/attention, turns, context/history, model planning, execution/results, explicit delivery, LCM, jobs/children and runtime/revisions. Rust validates each proposed change against domain invariants. The public hook vocabulary is broad; arbitrary internal functions and database writes are not public mutation points.

Default attention/context/model/social policies are ordinary editable Python. Durable hooks are published module entrypoints, not cell-local closures. The workbench can discover, edit, test, bind and activate them. Ordinary callable skills still need no hook registration.

The important failure boundary #

A Python cell awaiting discord.send must not wait for a review callback queued behind itself in the same workbench. The independent hook worker solves that placement problem. Host invocation also releases transactions/mutation locks, permits its bounded read RPC and uses Rust-owned deadlines; otherwise moving the callback alone would not solve the deadlock.

Optional hook failure may produce documented degradation. Required send/execution review failure holds the specific operation. Durable ingress and operator cancellation/rollback remain available even when every Python process is unhealthy. Post-commit observers can retry without duplicating atomically recorded host commands; arbitrary direct Python effects still do not gain an exactly-once guarantee.

Self-editability improvement #

A single authoritative activation manifest references instructions/settings, skills/environment and hooks. A compatible hook-only edit activates a new worker without clearing workbench variables. Shared dependency changes replace all affected roles. In-flight attempts/effects remain epoch-pinned; observer activation has explicit cursors and does not replay old events merely because code changed. Broken candidate hooks cannot veto their own repair.

Plan delta #

Slice 2 now defines hook contracts and invocation state. New slice 3a implements the worker, defaults and dispatcher. Slice 4 uses hooks in the real turn loop rather than deferring them. Subsequent domain slices add their own hooks. Slice 9 adds component activation, dry runs and state/replay compatibility. Cutover adds hook latency, queue/backlog and blocked-worker tests.

The primary success case is now: improve attention, context/model policy, delivery formatting or result handling entirely in Python, activate it without Cargo, preserve a compatible live workbench, and keep accepted work and honest receipts through a failed next edit.