research-dangerous-shell-guard

hook PreToolUse multi-harness mode: enforce

Block dangerous shell side effects during active research sessions.

Registry Entry

Field	Value
id	research-dangerous-shell-guard
mode	enforce
degraded_behavior	audit when the harness payload does not expose a shell command
logical_event	PreToolUse
matcher	Bash|bash|run_shell_command
command	python3 {repo_root}/hooks/wagents-hook.py research-dangerous-shell-guard --harness {harness}
timeout	5
harnesses	["codex", "claude-code", "github-copilot", "gemini-cli"]

Note

Blocks high-risk shell during research; falls back to audit in degraded harness payloads. Complements the non-research destructive-shell-guard.

Full hook config + command reference

config/hook-registry.json (entry)

{
  "id": "research-dangerous-shell-guard",
  "description": "Block dangerous shell side effects during active research sessions.",
  "mode": "enforce",
  "degraded_behavior": "audit when the harness payload does not expose a shell command",
  "logical_event": "PreToolUse",
  "matcher": "Bash|bash|run_shell_command",
  "command": "python3 {repo_root}/hooks/wagents-hook.py research-dangerous-shell-guard --harness {harness}",
  "timeout": 5,
  "harnesses": [
    "codex",
    "claude-code",
    "github-copilot",
    "gemini-cli"
  ]
}

hooks/wagents-hook.py (delegating)

def _policy_dangerous_shell_guard(payload: NormalizedPayload) -> int:
    if not _state_active(payload) or _tool_name(payload) not in SHELL_TOOL_NAMES:
        return 0
    # ... delegates heavy logic or uses research_hook equivalent

See skills/research/scripts/research_hook.py for the canonical research shell policy implementation.

Resources

Hooks Hub All repo-managed lifecycle hooks.

wagents hooks Inspect and validate hooks via CLI.

research skill The driving research skill.

---

View source on GitHub