askit-build-hook

name	askit-build-hook
description	Creates and improves event-driven hooks (Advanced tier) for a plugin to the Advanced Skill Library Standard. Use when you need to add a hook, enforce a guard on a tool or session event, inject context, or document a hook's event, scope, and failure behavior.
metadata	{"version":"0.1.0","tier":"universal","audience":"advanced"}

askit-build-hook

Purpose

Author a plugin's hooks: event-driven enforcement or context injection (Standard sec 3.5). Hooks are an Advanced-tier capability. Two modes: create scaffolds a hook and its registration; improve raises an existing hook toward the bar (documentation, idempotency, actionable block messages). The hook SKILL is portable; what it authors is primarily a Claude capability (31 events) with a smaller Codex event set. Authoring depth is in references/authoring-hooks.md. Follows the shared builder contract (../../docs/reference/builder-pattern.md).

When to use

When the user asks to add, scaffold, author, or improve a hook (a PreToolUse / PostToolUse / Stop / SessionStart guard, a context injector, or any event-driven automation) for a plugin.

create mode

1. Brief interview: the event (for example PreToolUse), the trigger or matcher, the hook type (command / http / mcp_tool / prompt / agent), the scope (what it guards or injects), and the failure behavior (fail-safe block vs warn). Skip the interview if these are in context.
2. Author the hook and its registration. A plugin registers hooks in hooks/hooks.json using ${CLAUDE_PLUGIN_ROOT}; copy templates/hooks.json if none exists. Document the event, trigger, scope, and failure behavior (Standard sec 3.5 MUST).
3. For a blocking hook (for example a PreToolUse deny), write an ACTIONABLE message that states what was blocked and how to proceed. Make the hook idempotent where the event can repeat.
4. Register the hook in library.json components.hooks as { name, version, tier, status }.
5. Targets: Claude supports 31 events. Codex supports a smaller set (PreToolUse, PostToolUse, Pre/PostCompact, SessionStart, SubagentStart/Stop, UserPromptSubmit, Stop, PermissionRequest). Verify current Codex plugin-hook ingestion at build time (a known caveat) and scope agent-targets accordingly.
6. Assess with node scripts/evaluate.mjs . --json. Hook documentation and idempotency are graded at the Advanced tier; the deterministic hook check lands with Gold self-hosting (Phase 5).

improve mode

1. Run node scripts/evaluate.mjs . --json and read the report.
2. Fix what it flags. For hooks specifically, confirm the event / trigger / scope / failure are documented (sec 3.5), the block message is actionable, and the hook is idempotent.
3. Re-run to confirm.

Scope

Hooks are Advanced-tier and the most agent-specific component: Claude's event set is the richest, Codex covers a subset, and the wider ecosystem does not support hooks. A hook MUST document its event, trigger, scope, and failure behavior, and a blocking hook MUST emit an actionable message (Standard sec 3.5). Least privilege applies (sec 9): a hook's command runs with the narrowest scope needed.