# Agent guardrails

An opencode plugin (`deploy/opencode-plugin/guardrails.js`) that intercepts
tool.execute calls and blocks or warns on patterns that have caused expensive
failures on this repo.

## Install

```
command cp -f deploy/opencode-plugin/guardrails.js ~/.config/opencode/plugins/
cp -n deploy/opencode-plugin/guardrails.example.json .omo/guardrails.json
```

Restart opencode. Check `~/.local/share/opencode/log/opencode.log` for
`failed to load plugin`.

## Uninstall

Delete `.omo/guardrails.json` (plugin goes inert) or remove
`guardrails.js` from `~/.config/opencode/plugins/`.

## Rule modes

Each rule can be `"block"` (default), `"warn"` (logs only, allows the
call), or `"off"` (no check). Edit in `.omo/guardrails.json`.

## Rules

| Rule | Blocks | Evidence |
|---|---|---|
| `task_needs_agent` | `task()`/`call_omo_agent` with no category, subagent_type, AND task_id | 2026-09-26..28: three such calls reported "completed" with zero work |
| `task_banned_agent` | `task()`/`call_omo_agent` to `oh-my-claudecode:*` agents | 2026-09-26: 12 dispatches to `oh-my-claudecode:writer` did zero work (pinned Anthropic model) |
| `task_worktree_line` | task prompt without `WORKTREE:` line when boulder has worktree_path, or mismatch | 2026-09-28: worker rewrote the main checkout's live config.yaml |
| `write_outside_worktree` | writes to files outside the worktree scope | same 2026-09-28 incident |
| `bash_main_checkout` | git/redirect ops targeting the main checkout from a worktree task | same class as 2026-09-28 main-checkout rewrite |
| `bash_banned` | `pkill`, `git stash`, `kill`, `systemctl` | 2026-09-26: unasked PR; 2026-09-29: git stash in wrong checkout |
| `bash_protected_port` | bash commands containing `localhost`, `127.0.0.1` or `0.0.0.0` followed by `:8080` (list: `protected_ports`) | 8080 is the production router and opencode's own model traffic runs through it (CLAUDE.md); 2026-08-29 incident #1: an agent `pkill`ed it to free the port for a throwaway, which belongs on 8081 |
| `plan_tick_gate` | tick gate blocks a todo tick while verify_commit fails | 2026-09-28: todo committed 3 failing tests and was reported done |

## Known gaps

Accepted on purpose; each was probed at the hook boundary. Revisit when an agent
is seen doing real damage through one of them, not before.

- **The plugin inspects only `task`, `call_omo_agent`, `edit`, `write` and
  `bash`.** `bash_protected_port` therefore does not see `webfetch` (or any MCP
  fetch tool): on 2026-10-04 a blocked `curl localhost:8080/health` was retried
  through `webfetch` and succeeded. A fetch is a GET; the calls that spend or
  change production (`/dispatch`, admin POSTs) normally go through bash, which
  is covered.
- **`bash_protected_port` matches literal text.** It misses `[::1]:8080`, the
  machine's own address, a URL held in a variable, and a script file that calls
  8080 internally. In the other direction, a commit message or argument that
  names `localhost:8080` is blocked. Text-only commands (`echo`, `grep`, `cat`,
  ...) and heredoc bodies are skipped unless fed to an interpreter. It does see
  inside `bash -c '...'` and `python3 -c '...'`, because it reads the raw string.
- **`bash -c '...'` and `sh -c '...'` wrappers are not inspected by
  `bash_banned` or `bash_main_checkout`.** `bash -c 'pkill -f foo'` and
  `bash -c 'git stash'` both pass.
- **`bash_main_checkout` can mis-anchor a relative `cd` chain that follows an
  absolute one** (one block in the replay report).

## Log

Blocks, warnings, and internal errors go to `.omo/guardrails.log` (JSON
lines, relative to the project root).

## Upstream

`scripts/verify_commit.py` and `scripts/oc_dispatch_audit.py` are the two
audit scripts the plugin and the agent procedures rely on.