research-readonly-write-guard

hook PreToolUse multi-harness mode: enforce

Prevent source-file write tools during active research sessions.

Registry Entry

Field	Value
id	research-readonly-write-guard
mode	enforce
degraded_behavior	audit when the harness payload does not expose a tool name or writable path
logical_event	PreToolUse
matcher	Write|Edit|MultiEdit|apply_patch|edit|create|replace|write_file|run_shell_command
command	python3 {repo_root}/hooks/wagents-hook.py research-readonly-write-guard --harness {harness}
timeout	5
harnesses	["codex", "claude-code", "github-copilot", "gemini-cli"]

Note

Policy _policy_readonly_write_guard delegates to research_hook for state; blocks writes when research state active. Degraded = audit only.

Full hook config + command reference

config/hook-registry.json (entry)

{
  "id": "research-readonly-write-guard",
  "description": "Prevent source-file write tools during active research sessions.",
  "mode": "enforce",
  "degraded_behavior": "audit when the harness payload does not expose a tool name or writable path",
  "logical_event": "PreToolUse",
  "matcher": "Write|Edit|MultiEdit|apply_patch|edit|create|replace|write_file|run_shell_command",
  "command": "python3 {repo_root}/hooks/wagents-hook.py research-readonly-write-guard --harness {harness}",
  "timeout": 5,
  "harnesses": [
    "codex",
    "claude-code",
    "github-copilot",
    "gemini-cli"
  ]
}

hooks/wagents-hook.py + research_hook.py

def _policy_readonly_write_guard(payload: NormalizedPayload) -> int:
    research_hook = _load_research_hook_module()
    research_payload = _research_payload(payload, research_hook)
    return research_hook._policy_readonly_write_guard(research_payload)

Full logic in skills/research/scripts/research_hook.py.

Resources

Hooks Hub All repo-managed lifecycle hooks.

wagents hooks Inspect and validate hooks via CLI.

research skill Pairs with research guards and ledger.

---

View source on GitHub