cc-hooks

cc:cc-hooks — Multi-Agent Hook System

Author hooks once in the rulesync-canonical format, deploy to Claude Code, Codex, OpenCode, Pi, and Gemini CLI.

Overview

Hooks execute in response to specific events during a coding agent session. Use this skill when implementing hooks for security validation, quality enforcement, context loading, or workflow automation across multiple coding agents: author once in the canonical hooks.json (HookDefinitionSchema), deploy to 5+ agents.

Canonical Schema (HookDefinitionSchema)

Hooks are authored as a rulesync-canonical hooks.json in the .rulesync/ directory of a plugin. The schema is defined in vendors/rulesync/src/types/hooks.ts:26 as HookDefinitionSchema:

{
  "hooks": {
    "<HookEvent>": [
      {
        "type": "command",            // "command" | "prompt" | "http"
        "command": "superskill hook run <plugin> <hook-id>", // portable PATH command (see below)
        "matcher": "Write|Edit",       // tool-name regex (control chars stripped)
        "timeout": 5000,               // ms; optional
        "failClosed": true,            // optional — block action on hook failure (Cursor)
        "loop_limit": 3,               // optional — prompt re-injection cap
        "name": "write-guard",         // optional
        "description": "Block dangerous writes" // optional
      }
    ]
  }
}

Field semantics:

• type: "command" (deterministic, runs anywhere), "prompt" (Claude Code only — natural-language validation), "http" (webhook).
• command / matcher / prompt: safeString — must not contain \n, \r, or \0 (they are embedded in generated code).
• timeout: milliseconds before the hook is killed.
• failClosed: when true, a hook failure (crash, timeout, invalid JSON) blocks the action instead of allowing it through. Default failOpen where unsupported.
• loop_limit: cap on prompt re-injections; null means unlimited.

HookEvent Taxonomy

Canonical event names are camelCase. Each tool supports a subset — see vendors/rulesync/src/types/hooks.ts:49 for the full HookEvent union.