Wiring the Proactive Layer into the Code — Design#

The proactive design itself lives in ../proactive/. This document covers only where that design meets the existing OpenProgram code: which mechanisms it reuses, where events are emitted, where the gate mounts, and what its enforcement actually covers. On any conflict the design documents win.

1. Where the code lives#

The event layer is an in-place upgrade of openprogram/events/bus.py: Event, subscription by event type, and a process-level singleton. Taps live in the individual source files that already know when something happened, not in a central collector. The openprogram/proactive/ package holds the rule layer and is created only when the first rule consumer arrives; the event layer is useful on its own before then.

The event model is the three core fields plus an open metadata pocket (design event-layer.md §1). turn and session travel in metadata rather than as fixed fields, so a source that has no notion of a turn is not forced to invent one.

2. Mechanisms reused rather than rebuilt#

Each role the design describes already has a working implementation in the codebase:

3. Event taps#

Events are emitted from the places that already detect the underlying fact. Most taps convert an existing callback or internal event into a canonical event rather than adding new detection:

4. Gate mounting and honest coverage#

The gate mounts at two places with genuinely different guarantees, and the difference is stated rather than papered over.

Chat path — hard enforcement. The gate is chained into _execute_tool_calls in agent_loop.py, ahead of tool.execute. Every chat tool call passes through this one point, so nothing routes around the gate.

Agentic nested path — optional mount. _pre_invocation_hooks in function.py, where the cancel check already hangs. This is a mount point, not a chokepoint; its coverage is declared for what it is and no claim of total coverage is made for nested calls.

The gate takes effect on subagent turns independently of permission_mode. In particular it is not disabled by the permission_mode="bypass" set in sub_agent_run.py — that bypass is an existing hole this design closes (design invariants.md and execution-model.md §2).

5. Prepare execution#

Prepare reuses JobRunner.spawn_job with a restricted tool allowlist that excludes bash, write, and network tools. It runs in a separate small pool at concurrency 1–2, is preemptible by user tasks, and yields on 429 (design execution-model.md §3).

6. A known gap, deliberately not blocking#

@function tool execution does not write a DAG node; only Agent method does. The DAG tree is therefore incomplete as a causal record. If auditing had to rely on the DAG for causal traceback, this would have to be filled first. Instead the design records the full event set independently in events.jsonl, which makes the DAG gap a known item rather than a prerequisite.

7. Verification approach#

Every wiring change is checked the same way: py_compile, the relevant unit tests, the repository's documented local refresh flow, a healthy /healthz, and a real message sent through the web UI (frontend changes need npm --prefix apps/web run build first).

Event ordering is checked by running a turn that calls a tool and reading the session's events.jsonl (the event log is always on). The log must show user.prompt_submitted → model.response_started → tool.before → tool.after → model.response_completed in that order, each entry carrying session and turn in its metadata.

Appendix: Implementation Status#

The bus, source taps, external-source bridge, subscriber-based web UI, and the openprogram/proactive/ package are present in the current source. The rule layer entry point is openprogram/proactive/engine.py::install_proactive, with policies under openprogram/proactive/policies/. The package and policies are implemented, but the current openprogram/worker/runner.py does not call install_proactive() at worker startup; only the separate event bridge is installed there. Worker lifecycle integration therefore remains an explicit unimplemented boundary. The original five-step sequence is retained as design history; current implementation status is determined from the paths and tests below.

As built, the pieces sit here:

The unit suite covers the event bus, tool gate, event bridges, and proactive policies. Installed-App and live WebSocket acceptance are separate checks and are not claimed by this design record. One environment note carried forward: the worker's working directory is the home directory, so the project skills directory resolves to ~/skills.