global-agent-guardrails · diff
git:20261012.bbafe9d to git:20261018.eaed515
22 added, 20 removed. Audit A to A.
---
name: global-agent-guardrails
- description: "Configure a shared guard against catastrophic shell commands in local AI agents. Use when changing block patterns, adding an agent or machine, or investigating why a command was or wasn't blocked."
+ description: "Configure the shared guard against catastrophic shell commands in local AI agents. Use when changing block patterns, adding an agent or machine, or investigating why a command was or wasn't blocked."
---
# Global Agent Guardrails
- Block catastrophic shell commands before execution. One patterns file can feed 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).
+ 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](https://www.cloudroom.dev/security) ships a built-in Command Guard based on this one, on by default.
+
## File map
- A typical setup has a patterns file, a shared guard, a test suite, and adapters for supported agents. Use your own documented configuration locations; avoid publishing machine-specific wiring details.
+ 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 guard and patterns file exist, then run the project's guard test suite. Tests should report no failures.
+ Confirm the shared guard and patterns are present, then run the test suite; it should report no failures.
- If missing, rebuild from the wiring table or other documentation for your setup.
+ If missing, rebuild from the wiring documentation in the project documentation.
## Add or tune a pattern
- 1. Edit the 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.
+ 1. 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.
2. Add block and allow cases to the test suite, then run it; all must pass.
- 3. Verify the new pattern compiles in the adapter engines using the project's documented validation method.
- 4. Ensure any native adapters are updated to match the shared patterns.
+ 3. Verify the new pattern compiles in each adapter's regex engine.
+ 4. 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)
- Use each agent's documented hook or native blocklist mechanism. Keep shared guard behavior consistent across adapters, and merge configuration into existing settings rather than overwriting them. Use absolute paths in configs when path expansion is inconsistent across agents.
+ 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 agent configurations require renewed trust after hook entries change. Check the agent's documentation and verify the guard is still active.
- - Fail-closed behavior can block commands in environments that cannot execute hook scripts. Consider the trade-off for background or worker agents.
- - Some plugin systems require explicit enablement. Verify the plugin is enabled and keep hook code simple.
- - Handle adapter errors deliberately: depending on the agent, an error may block a tool or allow it to proceed.
- - Distinguish confirmation behavior from hard-block behavior in native command filters.
- - Make sure the guard reads the command field used by each agent's payload format.
- - **Adapter regexes require multiline mode.** Keep JavaScript's `m` flag and Python's `re.M` so `^` matches each shell line like `grep`.
- - **False-positive class:** a harmless command whose argument text contains a dangerous-looking string (e.g. passing a prompt mentioning `git push --force` on a CLI) gets blocked. Workaround: put the text in a file and reference it.
- - Some agents or hosted/background environments may not support local command hooks. Check current agent documentation and account for any paths that bypass the local guard.
+ - 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 disposable, non-git directory: ask the agent to run a command that should be blocked, and confirm the guard blocks it. A repository-related error instead of a guard block means the test did not verify the guard. Follow each agent's documented procedure and avoid bypassing permission safeguards during 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.
- For a direct test, send a representative dangerous-command payload to the guard and confirm it returns the documented block result.
+ Run the guard's test suite directly to verify that a catastrophic command is blocked.