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).

32 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.

Cursor-specific

Cursor uses the Python dispatcher (wagents-hook.py) plus its own native lifecycle events (beforeReadFile, beforeShellExecution, beforeMCPExecution, afterFileEdit, subagentStart). Enforce-tier native events are rendered fail-closed.

cursor-session-start-context

SessionStart context Lightweight Cursor session + repo context.

cursor-destructive-shell-guard

PreToolUse enforce Block critical destructive shell commands in Cursor.

cursor-protected-file-guard

PreToolUse enforce Block protected files, secret paths, git internals, traversal, and lockfile edits.

cursor-post-tool-verify-context

PostToolUse context Lightweight post-edit quality checks + verification guidance.

cursor-stop-truth-gate

Stop enforce Ask for one more pass when final claims omit validation evidence.

cursor-before-read-file-guard

BeforeReadFile enforce Block reads of secret-bearing files before they enter Cursor context.

cursor-before-shell-execution-guard

BeforeShellExecution enforce Block destructive shell + unsafe git history rewrites pre-execution.

Shell guard layering: cursor-destructive-shell-guard on preToolUse and cursor-before-shell-execution-guard on beforeShellExecution intentionally overlap for defense-in-depth — legacy preToolUse coverage plus native pre-execution hooks (including cloud agents that lack stop).

cursor-before-mcp-execution-guard

BeforeMCPExecution enforce Block destructive MCP tool calls before execution.

cursor-after-file-edit-context

AfterFileEdit context Lightweight post-edit quality context after file edits.

cursor-subagent-start-context

SubagentStart context Inject repo conventions + session context when a subagent starts.

Cross-harness safety & optimization

Tier B policies that span codex, claude-code, cursor, github-copilot, and gemini-cli via the shared dispatcher. Grok consumes them through the fleet deny adapter (~/.grok/hooks/wagents-fleet.json).

git-commit-push-guard

PreToolUse enforce Block force-pushes to protected branches, hook-skipping commits, and unsafe history rewrites.

image-input-optimizer-guard

PreToolUse enforce Resize + compress oversized local image inputs before harnesses consume them.

Claude-specific

Claude Code uses Stop / SubagentStop quality gates wired through .claude/settings.json.

verify-before-stop

Stop enforce Block stopping when modified files carry debug artifacts or fail fast lint/type checks.

task-completed-gate

Stop enforce Block completion on syntax errors, incomplete markers, or failing tests.

teammate-idle-gate

SubagentStop enforce Block a subagent from going idle with broken syntax or critical failures.

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, Cursor + multi-harness policies use hooks/wagents-hook.py <policy-id> --harness <name>. Payload normalization, state, ledger, and degraded modes live here.
• Cursor native events (beforeReadFile, beforeShellExecution, beforeMCPExecution, afterFileEdit, subagentStart) are rendered into the flat .cursor/hooks.json shape; enforce-tier guards are fail-closed.
• Decision logic is being migrated into pure modules under wagents/hooks/policies/ (e.g. git_commit_push_guard, before_read_file_guard, before_mcp_execution, subagent_start, grok_deny_adapter) so the dispatcher stays thin and unit-testable.
• Grok consumes the dispatcher-backed fleet via a deny adapter (render_grok_hooks → ~/.grok/hooks/wagents-fleet.json); OpenCode bridges enforce-tier PreToolUse guards through platforms/opencode/plugins/wagents-hook-bridge.ts.
• 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.

Runtime performance tiers

Fleet hook rendering supports staged performance tiers via config/tooling-policy.json:

"hook_perf": { "tier": "bundle" }

Tier	Behavior
legacy	One rendered entry per registry row — byte-identical to pre-performance baselines (rollback tier).
g1	Registry quick wins (matcher narrowing, dispatcher caches) without bundling.
bundle	Consecutive bundle_group rows collapse to a single {hook_runner} --bundle ... spawn.
worker	Bundle groups render through hooks/wagents-hook-worker.py (optional warm-process path).

The worker daemon (python3 hooks/wagents-hook-worker.py --serve --socket PATH) handles one socket connection at a time: its accept loop serves each NDJSON request to completion before accepting the next client. Parallel harness hook events queue at the socket backlog; this is acceptable for enforce-chain bundle semantics. Start the daemon and set WAGENTS_HOOK_WORKER_SOCKET to the socket path before promoting hook_perf.tier to worker and running sync_agent_stack.py --apply — rendered commands forward through wagents-hook.py --worker-socket and will fail closed or fall back if the socket is absent.

Observability: set WAGENTS_HOOK_TIMING=1 on a hook invocation to append JSON timing lines to ~/.cache/wagents/hook-timing.jsonl. Worker-tier forwards (--worker-socket) record the same sidecar with "forwarded": true so hyperfine runs can distinguish warm socket paths from cold spawns. Bundle worker forwards use a socket wait budget of bundle_timeout + 1s (aligned with the OpenCode bridge margin). Inventory spawn counts with uv run python scripts/hooks/hook_perf_inventory.py --json.

The repo default tier is bundle after Hooks Bundle Promotion v2 (openspec/changes/fleet-hooks-promotion/). Committed spawn baselines live under docs/public/generated-reports/hook-perf-baseline-*.json. Maintainer workflow: docs/runbooks/hook-performance.md. Promote to worker only after hyperfine validation documented in openspec/changes/fleet-hooks-performance/validation-matrix.md.

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