Agent loop monitor
Loop · BB IDE plugin
A live dashboard for an agent's guard rails, fed by shell hooks that will not let a turn end while the build is red.
Problem
Hook-gated agent runs are safer, but opaque. The stage the agent reached, how many times the check has failed, and whether a scope gate refused an edit all lived inside a long transcript.
Constraints
- It lives inside an IDE it does not control, through the plugin SDK only.
- Hooks run on every tool call, so each report is capped at two seconds and must never block the agent.
- Several threads can share one worktree and write stage files into the same checkout.
How it works
- A pre-tool hook records a git baseline per repository; a scope gate denies edits outside the task's allowed paths.
- A stop hook runs the project's declared check and refuses the turn while it is red.
- Skills stamp the current stage into the workspace, tagged with the thread that wrote it.
- Every hook posts its decision to the plugin server, which keeps per-thread state and publishes it in real time to the Loop tab, the header badge and a `bb loop status` command.
Decisions
- Programs decide green, not the model: the project declares its own check and the hook never guesses. An unknown stack stays silent.
- Only repositories this session changed are checked, so a stray directory change cannot block a turn.
- Failure output is hashed with timings stripped; a repeated hash tells the agent to stop retrying the same fix.
- A stage written by another thread in a shared worktree shows as foreign instead of being mistaken for this one.
- State logic has no IDE imports, so it is unit-tested on its own, and every inbound event is validated.
Trade-offs
- The scope gate catches drift, not a hostile agent; the permission deny list stays the hard limit.
- State lives per thread and is dropped with the thread, so the panel shows the run, not a history.
Safeguards
- Three attempts, then the turn is released to the human with the failure attached.
- Hook reports time out after two seconds and do nothing outside the IDE.
- Per-thread state is dropped when its thread is deleted, so nothing outlives the run it describes.
Limits
- It is only as useful as the project's declared check: a stack with no check stays silent by design.
In numbers
- 6 stage codes
- 3-attempt limit
- 16 tests
- About 690 lines of plugin code