Global Agent Guardrails
Block catastrophic shell commands before execution. One patterns file feeds a shared hook script or native adapter for each agent. This guards against accidents, not malicious agents (obfuscation like python -c "shutil.rmtree(...)" can slip past regex).
Cloudroom ships a built-in Command Guard based on this one, on by default.
File map
The setup consists of a shared pattern list, a guard script, a test suite, and agent-specific adapters. Keep those in the appropriate user-level configuration locations for your tools.
Check installation
Confirm the shared guard and patterns are present, then run the test suite; it should report no failures.
If missing, rebuild from the wiring documentation in the project documentation.
Add or tune a pattern
- Edit the shared patterns file. Write POSIX ERE (
grep -E). Use [[:space:]], never \s — adapters may convert [:space:] to \s for JS/Python and compile in multiline mode.
- Add block and allow cases to the test suite, then run it; all must pass.
- Verify the new pattern compiles in each adapter's regex engine.
- Consumers should re-read patterns for every command. If an agent uses a native blocklist, mirror changes there as appropriate.
Block only catastrophic commands (irreversible data loss, disk wipes, repo deletion). Recoverable local commands stay allowed; avoid over-blocking.
Per-agent wiring (user-global)
Configure each agent using its documented hook or native command-blocking mechanism. Where supported, point the hook to the shared guard; merge settings into existing configuration rather than overwriting it. Use absolute paths in configs where path expansion is inconsistent.
Gotchas
- Some agents pin hook trust to configuration contents. After changing hook configuration, follow the agent's documented trust or approval process.
- Some background or worker environments cannot execute local hook scripts. Check the agent's documentation for failure behavior and limitations.
- Plugin hook manifests, enablement, and failure behavior vary by agent; keep adapters simple and follow each tool's public documentation.
- Adapters should handle errors deliberately so a broken patterns file does not unexpectedly block every command.
- Native blocklist semantics vary: some entries request confirmation while others prevent execution. Use the strongest appropriate mechanism for catastrophic commands.
- Ensure the guard reads the command from the payload format used by each integration.
- Adapter regexes may require multiline mode so
^ matches each shell line like grep.
- False-positive class: a harmless command whose argument text contains a dangerous-looking string can get blocked. Workaround: put the text in a file and reference it.
- Some agents or remote/background execution environments may not support local hooks. Check the relevant agent documentation for current support.
E2E verification
Use a safe probe in a temporary, non-git directory: ask the agent to run a command that would be blocked if executed. A guard block indicates the guard works; a repository-context error indicates the probe did not test the guard.
Run the guard's test suite directly to verify that a catastrophic command is blocked.