docs/agent-guardrails.md

@@ -34,9 +34,32 @@ call), or `"off"` (no check). Edit in `.omo/guardrails.json`.
 | `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` | curl/wget targeting port 8080 | port 8080 is production — CLAUDE.md |
+| `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