avizmarlon/hooks-multi-tool-parity

Hook Lifecycle Propagation Across All AI Tools

When you manage hooks in a multi-AI environment, hook definitions must propagate across all AI tools that have equivalent lifecycle support. This prevents gaps where a behavioral rule is enforced in one tool but leaves others unprotected.

Why This Matters

When multiple AI tools (Claude Code, Codex, Cursor, Gemini, Kimi, Desktop Commander, Cline) are used in parallel or in sequence within the same workflow:

• A bug-mitigation hook (e.g., confabulation detection, evidence-validation checks) implemented in one tool leaves others exposed
• Divergent hook implementations create hidden dependencies and make reasoning harder to audit
• Asymmetric enforcement creates false confidence in safety: one tool appears "hardened" while others follow the same failure mode

Example failure scenario: You implement a validation hook in Claude Code that prevents certain classes of faulty claims. Codex, used in parallel, lacks this hook. Both tools can produce the same error, but you've only patched half your stack.

Propagation Framework

Tool Categories by Hook Support

Different tools have varying hook lifecycle maturity. Organize propagation as tiers:

| Tool | Hook Events | Propagation Tier | Configuration | |---|---|---|---| | Claude Code | SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop | Primary | ~/.claude/hooks/ + settings.json | | Codex CLI | SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd | Primary | ~/.codex/hooks/ + config file | | Cursor | Startup, ToolExecution, FileEdit, Completion, Shutdown | Best-effort | IDE plugin config + rules directory | | Gemini CLI | Startup, Shutdown, BeforeAgent | Best-effort | Settings file | | Kimi Desktop / CLI | Tool-specific hooks | Best-effort | App config | | Desktop Commander | Tool-specific hooks | Best-effort | Application config | | Cline | BeforeToolExecution, AfterToolExecution, OnNotification | Best-effort | SDK hook configuration |

Definitions:

• Primary: Hook must propagate in the same session. Treat as a blocking requirement.
• Best-effort: Propagate when the tool supports an equivalent event and the hook is semantically applicable. Document gaps in handoff documentation.

Semantic Event Mapping

Events are not always 1:1 between tools. Map by semantic meaning:

| Semantic Intent | Claude Code | Codex | Cursor | Gemini | Action | |---|---|---|---|---|---| | Before execution starts | SessionStart | SessionStart | Startup | Startup | ✅ All supported | | User submits prompt | UserPromptSubmit | UserPromptSubmit | (via Completion) | BeforeAgent | ✅ Propagate | | Pre-tool invocation | PreToolUse | PreToolUse | ToolExecution | (no equivalent) | ✅ Propagate where available | | Post-tool result | PostToolUse | PostToolUse | ToolExecution | (no equivalent) | ✅ Propagate where available | | Session ends | Stop / SessionEnd | Stop / SessionEnd | Shutdown | Shutdown | ✅ All supported | | Before cleanup | PreCompact | (no equivalent) | (no equivalent) | (no equivalent) | ⚠️ Claude-only; document gap |

Apply the rule: if a hook's purpose is tool-agnostic (e.g., "validate all claims before tool use"), it belongs in every tool that fires the equivalent event.

Operational Flow

When a hook is created, modified, or removed:

1. Identify primary tool — where is the hook being initially developed? (Claude Code, Codex, etc.)
2. Same session: propagate to other primary tool — if you added a hook in Claude Code, port it to Codex in the same session. No "I'll do it later."
3. Map events to secondary tools — check Cursor, Gemini, Kimi, etc. If an equivalent event exists and the hook's purpose applies, implement it.
4. Document gaps — if Tool X has no equivalent event (e.g., Claude's PreCompact doesn't exist in Codex), record this in your handoff documentation with the reason.
5. Update instruction files — add propagation notes to your global instruction sets (e.g., CLAUDE.md for Claude Code, AGENTS.md for Codex, etc.).
6. Smoke test each tool — before finalizing, run the hook in each tool and verify expected behavior.

Example: Implementing a Cross-Tool Validation Hook

Scenario: You need a hook to prevent "unsourced claims" — any time an AI tool generates a factual assertion, the hook checks for inline evidence.

Steps:

1. Claude Code: Write hook in ~/.claude/hooks/pre-tool-use.js that intercepts tool calls and validates claim structure.
2. Codex CLI (same session): Implement equivalent logic in ~/.codex/hooks/pre-tool-use.js using Codex's hook API.
3. Cursor: If Cursor's ToolExecution hook supports inspection, add validation there; if not, document "Unsourced-claim validation not available in Cursor (no equivalent event)."
4. Gemini: Gemini lacks a pre-tool-execution hook → document gap; Gemini only validates at Startup or BeforeAgent, so adapt logic to run early or skip.
5. Update CLAUDE.md / AGENTS.md with note: "Unsourced-claim validation hook propagated to Claude Code + Codex CLI (primary); Cursor best-effort via custom rule; Gemini gap documented."
6. Test: Run the same prompt in Claude Code, Codex, and Cursor; verify hook fires in all three.

Anti-Patterns to Avoid

Prohibited:

• Creating a hook in Claude Code and deferring propagation to Codex: "I'll port it later." → Port in the same session.
• Ignoring tool gaps silently: "Tool X doesn't support this hook, so I'll just leave it." → Document the gap explicitly; don't let divergence hide.
• Implementing divergent logic across tools without justification: Different regex, thresholds, or behavior in Claude vs. Codex without a recorded reason. → Divergence only when tool shape genuinely requires it (e.g., transcript format differs); logic should be semantically identical.
• Using different environment variables to disable hooks across tools when behavior is symmetric: HOOK_DISABLE for Claude, DISABLE_HOOK for Codex. → Consolidate to one disable switch (e.g., AUDIT_HOOKS_DISABLED=1 disables the same hook everywhere).

Handoff Documentation

Maintain a hook-parity audit trail in your handoff documentation. Example:

markdown
## Hook Propagation Status (Current Session)

### Hooks Modified
- **unsourced-claim-validation** (YYYY-MM-DD)
  - Claude Code: ✅ Implemented in hook directory
  - Codex CLI: ✅ Ported to equivalent hook location
  - Cursor: ✅ Adapted as custom rule in IDE config
  - Gemini: ⚠️ Gap — no pre-tool event; skipped
  - Kimi: ⚠️ Unknown tool support; best-effort pending testing

### Propagation Debt
- (None currently)

### Known Gaps
- Cursor lacks pre-tool-use lifecycle event; validation fires post-execution only
- Gemini Hook API limited to Startup/Shutdown/BeforeAgent; no mid-execution hooks

When Hook Parity is Not Required

Hook parity is a safety/consistency requirement for behavioral enforcement hooks (validation, claim-checking, guardrails, error-handling). Conversely:

• Logging/observability hooks that are tool-specific may stay in one tool only (e.g., Claude's SessionStart writes to Claude's log only).
• UI-only hooks (e.g., Cursor plugin displaying a status bar) don't need propagation; Cursor-specific is fine.
• Experimental hooks in alpha/beta may be single-tool only, documented as "Pending propagation."

If unsure, ask: "Would a user expect this behavior to apply consistently across all my AI tools?" If yes → propagate. If no → document as tool-specific.

See also: agent-runtime-parity (broader sync for rules, skills, MCPs, APIs, credentials, and memory across all AI surfaces).