Gate the action, keep the record

What exactly did I approve?

When several coding agents are working, a request for permission needs context: which project, which action, and which decision will let the work continue? I built BigBoss to put those requests in one local queue and retain the decisions afterward.

My contribution is the dashboard, policy routing, SQLite approval store, and adapters connecting the workflow to coding harnesses, developed with AI assistance. It is a personal working MVP built with Python’s standard library, Server-Sent Events, and a static web interface.

The question behind it is practical: how can a person keep useful control as the amount of agent work grows?

From proposed action to recorded decision

1. Receive a proposal

   An adapter submits the proposed action with its workspace, run, and a summary for the reviewer.

2. Route it through policy

   BigBoss classifies the request as automatically allowed, pending review, or blocked. Structured read-only actions can proceed; file changes and shell commands enter review under the default policy.

3. Let the person decide

   The dashboard presents the request. The reviewer can approve, reject, or request changes with an instruction.

4. Retain the decision

   SQLite stores requests, decisions, and events. An adapter receives the outcome and must match execution to the action that was approved.

Read the classification policy and approval store.

Approval belongs to a specific proposal

A general “yes” is ambiguous if an agent changes its command afterward. BigBoss stores an action_hash derived from the proposed action, workspace, and policy version. The adapter contract requires execution to match that returned hash.

This makes the approved proposal identifiable. Enforcement still depends on an integrated adapter honoring the contract. What that binding does and does not cover is spelled out below.

Keeping state in SQLite also means the decision history is separate from a terminal session. The store tests express expected behavior for request creation, decisions, and retained events.

What holds, and what does not

BigBoss makes proposed actions visible, attributable, and auditable, and holds a gated action until a decision is recorded. Within that scope the guarantees below hold. They are not the same as host isolation.

Holds

• A decision is bound to the action_hash, workspace, and policy version, and to an enrolled device token, so an adapter may execute only the exact action that device approved.
• Every request, decision, and enrollment is written to the event log.
• The local MCP facade exposes no approve or reject tool; paired devices remain the decision authority.

Does not hold

• Loopback enrollment is not isolation. The server binds 127.0.0.1; any process that can reach that API can enroll a device without a human step.
• A co-located harness that can make local HTTP calls can self-pair and approve its own cards.
• Keeping the governed harness away from the approval API (separate OS user, sandbox, or host) is the operator’s duty, not something the workflow provides by itself.

Full wording lives in the repository’s Security model.

The adapter is part of the design

The public implementation includes an HTTP interface, a local MCP facade, a hook adapter, and a Codex app-server bridge. They connect different kinds of harness events to the same approval store.

The distinction between a status update and an approval request matters. The documented Codex approval path uses its app-server protocol; the repository notes that project hooks do not provide that approval path under codex exec. An integration needs to participate at the point where the harness is waiting for a decision.

Inspect the bridge or follow the repository’s adapter documentation for its current setup and boundaries.

A small local workflow to try

The quickstart starts the local dashboard and submits a demonstration request. It gives a reviewer a way to inspect the request card and decision flow without connecting a live agent first.

The current scope is one human authority per instance. It binds locally by default; phone access is opt-in on the local network and requires the web app to remain open for alerts. There is no hosted service or relay in this release.

Run the checks yourself

Version v0.1.0 is tagged so the test suite can be run from a fixed point rather than a moving branch. Continuous integration runs that suite on Ubuntu and Windows against Python 3.12 and 3.13, with no vendor API keys configured: 399 tests pass, none skipped, in all four jobs. Cloning the tag and running the suite reproduces the same result locally.

This is my own automation on hosted runners. It is not independent reproduction, and none is claimed here; the repository states the same limitation. An independent reproduction is welcome and the repository explains how to file one.