Hooks

Repo-managed, portable lifecycle hooks declared in config/hook-registry.json. These provide safety, context, formatting, lint, research guards, and audit surfaces across harnesses. Hand-maintained catalog pages (composed).

17 hooks

Source of truth

All hooks are defined in config/hook-registry.json. Use wagents hooks list and wagents hooks validate to inspect at runtime. Individual hook pages live under /hooks/<id>/.

Core (github-copilot baseline)

These run for the GitHub Copilot harness via direct shell handlers.

session-start

SessionStart Report basic session environment and repository state (branch, dirty files, tool presence).

prompt-log

UserPromptSubmit Local prompt audit logging (short retention) for Copilot sessions.

destructive-shell-guard

PreToolUse Block rm -rf on critical paths, remote-pipe-to-shell, force-push to main, git reset —hard, git clean -f.

protected-file-guard

PreToolUse Deny edits to secrets (.env*, credentials, tokens), .git internals, lockfiles, and path traversal.

post-edit-format

PostToolUse Best-effort auto-format for py (ruff), js/ts (prettier), rs, go after writes/edits.

post-edit-lint

PostToolUse Return concise Ruff/Ty or tsc issues as additionalContext after edits (non-blocking).

Codex-specific

Codex harness uses the Python dispatcher (wagents-hook.py) for richer policy + status messages. All are registry-sourced.

codex-session-start-context

SessionStart context Lightweight git + repo context for Codex sessions.

codex-destructive-shell-guard

PreToolUse enforce Critical shell blocks tailored for Codex payloads.

codex-protected-file-guard

PreToolUse enforce Expanded matcher covering writes + shell for Codex protected-path enforcement.

codex-permission-request-guard

PermissionRequest enforce Deny high-risk permission requests while preserving normal approval flow.

codex-post-tool-verify-context

PostToolUse context Lightweight quality checks + guidance injected as context (no block).

codex-stop-truth-gate

Stop enforce Require validation evidence before allowing stop when code-change claims are present.

Research guards (multi-harness)

Activated by research prompts. Span codex, claude-code, github-copilot, gemini-cli. Use state machine + ledger for invariants.

research-prompt-triage-context

UserPromptSubmit context Detects research intent, activates state, injects method reminders.

research-readonly-write-guard

PreToolUse enforce Blocks source writes while research state is active (degraded=audit).

research-dangerous-shell-guard

PreToolUse enforce Blocks dangerous shell during research (degraded=audit).

research-evidence-ledger

PostToolUse audit Appends provenance (URLs, retrieval tools) to per-session ledger for later verification.

research-stop-verifier

Stop enforce Final invariant checks (ledger, claims, state) before allowing research session to stop. 30s timeout.

Dispatcher & Implementation Notes

• GitHub Copilot direct .sh handlers under ./hooks/.
• Codex + multi-harness research use hooks/wagents-hook.py <policy-id> --harness <name>. Payload normalization, state, ledger, and degraded modes live here.
• Research policies also delegate to skills/research/scripts/research_hook.py for the full state machine and stop verifier.
• All entries are validated by wagents hooks validate and scripts/validate/validate_repo.py.

Related

• CLI: wagents hooks list --format json, wagents hooks validate
• Registry: config/hook-registry.json
• Safety surface also includes MCPHub groups and agent permissionMode settings.
• Research skill: /skills/catalog/custom/research/

---

View source on GitHub