Scaffold: New Hook Registration

This document is an entrypoint for hook scaffolding. The step-by-step flow is in /.system/skills/ssot/repo/scaffolding/new-hook/SKILL.md.

1. Purpose & Scope

Purpose: Register a new hook that responds to lifecycle events (PromptSubmit, PreAbilityCreate, PreAbilityCall, PostAbilityCall, SessionStop).

Scope:

•Creates hook registration in /.system/hooks/
•Validates handler references
•Optionally creates handler implementation placeholder

Out of scope:

•Implementing the actual handler logic
•Modifying existing hooks
•Runtime hook execution (handled by Hook Runner)

2. Inputs & Preconditions

Required Inputs

Parameter	Type	Description
`id`	string	Unique hook identifier (e.g., `ability_usage_tracker`)
`event_type`	enum	Lifecycle event: `PromptSubmit`, `PreAbilityCreate`, `PreAbilityCall`, `PostAbilityCall`, `SessionStop`
`enabled`	boolean	Whether hook is active
`blocking`	boolean	Whether hook blocks execution
`handler.kind`	enum	Handler type: `script`, `function`
`handler.command`	string	Handler command or function reference

Optional Inputs

Parameter	Type	Default	Description
`summary`	string	""	One-line description of what this hook does (max 200 chars)
`match`	object	{}	Selective execution conditions (ability_pattern, scope_pattern)
`order`	integer	100	Execution order (lower = earlier)

Preconditions

•Phase 4 registry tooling is available (scripts/devops/registry/hooks.py)
•id does not already exist in hook registry
•Handler reference is valid or will be created
•Hook file naming matches id (<id>.yaml)

3. Step-by-Step Flow (AI + Human)

See /.system/skills/ssot/repo/scaffolding/new-hook/SKILL.md.

4. Tools & Scripts

Tool	Purpose
`scripts/devops/scaffold/new_hook.py`	Orchestrator script
`scripts/devops/registry/hooks.py`	Hook validation

5. Outputs & Side Effects

Files Created

code

/.system/hooks/<id>.yaml                    # Hook registration
/.system/hooks/implementations/<id>.py      # Handler placeholder (optional)

Hook Registration Structure

yaml

id: ability_usage_tracker
event_type: PostAbilityCall
enabled: true
blocking: false
handler:
  kind: script
  command: scripts/hooks/<hook_id>.py
summary: Track ability usage for analytics
order: 100
match:
  ability_pattern: ".*"

6. Safety & Rollback

Safety Measures

•--dry-run always available for preview
•Human approval required before execution
•Schema validation on hook registration
•Consistency checks via hooks.py --check

Rollback Procedure

If registration fails or needs reverting:

•
Delete the hook file:
bash
```
rm /.system/hooks/<id>.yaml
```
•
Optionally delete the handler placeholder:
bash
```
rm /.system/hooks/implementations/<id>.py
```

•Verify with:

bash

python scripts/devops/registry/hooks.py --check

7. Event Type Reference

Event Type	When Triggered	Typical Use
`PromptSubmit`	User submits prompt	Routing hints, intent normalization
`PreAbilityCreate`	Before task.create	Preflight validation, policy checks
`PreAbilityCall`	Before task.run	Guardrails, approval gates
`PostAbilityCall`	After task execution	Logging, analytics, cleanup
`SessionStop`	Session ends	Summary generation, state persistence

8. Related Documents

•/.system/skills/ssot/repo/architecture-core-mechanisms/hook-lifecycle/SKILL.md - Hook lifecycle workflow
•/.system/hooks/AGENTS.md - Hook infrastructure strategy
•/.system/registry/schemas/hook.schema.yaml - Hook schema
•/.system/registry/schemas/V1_CORE.md - V1-core required fields