Hook Integration for Skills

Skills can be designed to work with Claude Code's 12 hook events, enabling deep integration with harnesses like Clausitron.

Available Hook Events

Hook Event	When It Fires	Skill Integration Opportunity
`PreToolUse`	Before any tool executes	Validation skills, policy enforcement
`PostToolUse`	After tool execution	Logging skills, result enrichment
`PostToolUseFailure`	When a tool fails	Error analysis skills, recovery suggestions
`UserPromptSubmit`	When user sends prompt	Context injection, prompt enhancement
`SessionStart`	Session begins	Environment setup, context loading
`SessionEnd`	Session ends	Summary generation, cleanup
`SubagentStart`	Subagent spawns	Budget allocation, tracking
`SubagentStop`	Subagent completes	Result aggregation, cost tracking
`Stop`	Agent stops	State persistence, handoff notes
`PreCompact`	Before context compaction	Archive important context
`PermissionRequest`	Permission dialog triggered	Policy-based auto-decisions
`Notification`	Agent status messages	External notifications (Slack, etc.)

Hook-Aware Skill Patterns

Pattern 1: Validation Skill (PreToolUse)

Skills that validate operations before they execute:

---
name: security-validator
description: Validates file operations for security compliance. Use with PreToolUse hook.
---

# Security Validator

## Hook Integration
This skill provides validation logic for PreToolUse hooks.

## Validation Rules

### File Write Validation
When `tool_name` is `Write` or `Edit`:
1. Check `file_path` against blocked patterns:
   - `*.env*` - Environment files with secrets
   - `*credentials*` - Credential files
   - `**/config/production/**` - Production configs
2. Return `permissionDecision: 'deny'` if blocked

### Bash Command Validation
When `tool_name` is `Bash`:
1. Parse `command` for dangerous patterns:
   - `rm -rf /` or `rm -rf ~`
   - `curl | bash` or `wget | sh`
   - Commands with `--force` on production paths
2. Return `permissionDecision: 'ask'` for review

Pattern 2: Context Injection Skill (SessionStart/UserPromptSubmit)

Skills that enrich context at key moments:

---
name: project-context
description: Injects project-specific context at session start. Use with SessionStart hook.
---

# Project Context Injector

## Hook Integration
Responds to SessionStart and UserPromptSubmit hooks.

## Context Injection

### On SessionStart
Read and inject:
- Active sprint goals from `docs/SPRINT.md`
- Recent changes from `git log --oneline -10`
- Known issues from `docs/KNOWN_ISSUES.md`

### On UserPromptSubmit
Analyze prompt for keywords and inject relevant:
- API documentation for mentioned endpoints
- Schema definitions for mentioned models
- Test patterns for mentioned components

Pattern 3: Summary Skill (SessionEnd/Stop)

Skills that generate summaries when sessions end:

---
name: session-summarizer
description: Generates session summaries on completion. Use with SessionEnd hook.
---

# Session Summarizer

## Hook Integration
Responds to SessionEnd and Stop hooks.

## Summary Generation

### Session Summary Format
```json
{
  "session_id": "{from hook input}",
  "duration_minutes": "{calculated}",
  "files_modified": ["{list from git status}"],
  "key_accomplishments": ["{extracted from conversation}"],
  "open_questions": ["{unresolved items}"],
  "next_steps": ["{suggested follow-ups}"]
}

Storage

Write summaries to:

.claude/session-summaries/{session_id}.json
Update .claude/HANDOFF.md with latest summary


### Pattern 4: Cost Tracking Skill (SubagentStart/SubagentStop)

Skills that monitor resource usage:

```markdown
---
name: cost-tracker
description: Tracks token usage and costs across subagents. Use with Subagent hooks.
---

# Cost Tracker

## Hook Integration
Responds to SubagentStart and SubagentStop hooks.

## Tracking Logic

### On SubagentStart
Record:
- `agent_id` from hook input
- `agent_type` for categorization
- Start timestamp
- Allocated budget (if applicable)

### On SubagentStop
Calculate:
- Token usage from result message
- Cost based on model pricing
- Duration
- Update running totals

### Budget Enforcement
If cumulative cost exceeds threshold:
- Log warning
- Can trigger `permissionDecision: 'deny'` on next PreToolUse

Hook Response Schemas

Skills that integrate with hooks should understand the response format:

// PreToolUse can return permission decisions
{
  hookSpecificOutput: {
    hookEventName: 'PreToolUse',
    permissionDecision: 'allow' | 'deny' | 'ask',
    permissionDecisionReason: 'Explanation shown to Claude',
    updatedInput: { /* modified tool input */ }
  }
}

// UserPromptSubmit can add context
{
  hookSpecificOutput: {
    hookEventName: 'UserPromptSubmit',
    additionalContext: 'Context injected into conversation'
  }
}

// SessionStart can add context
{
  hookSpecificOutput: {
    hookEventName: 'SessionStart',
    additionalContext: 'Startup context for Claude'
  }
}

// PostToolUse can add context
{
  hookSpecificOutput: {
    hookEventName: 'PostToolUse',
    additionalContext: 'Context after tool execution'
  }
}

// Any hook can inject system messages
{
  systemMessage: 'Message visible to Claude in conversation'
}

// Any hook can stop execution
{
  continue: false,
  stopReason: 'Why execution stopped'
}

Hook Input Schemas

Each hook receives specific input data:

PreToolUse Input

{
  hook_event_name: 'PreToolUse',
  session_id: string,
  tool_name: string,        // 'Bash', 'Write', 'Edit', etc.
  tool_input: {             // Tool-specific parameters
    command?: string,       // For Bash
    file_path?: string,     // For Write/Edit/Read
    content?: string,       // For Write
    // ... other tool params
  },
  cwd: string,
  transcript_path: string
}

SessionStart Input

{
  hook_event_name: 'SessionStart',
  session_id: string,
  source: 'startup' | 'resume' | 'clear' | 'compact',
  cwd: string,
  transcript_path: string
}

SessionEnd Input

{
  hook_event_name: 'SessionEnd',
  session_id: string,
  reason: string,  // 'clear', 'logout', 'prompt_input_exit', etc.
  cwd: string,
  transcript_path: string
}

SubagentStart Input

{
  hook_event_name: 'SubagentStart',
  session_id: string,
  agent_id: string,
  agent_type: string,
  cwd: string,
  transcript_path: string
}

SubagentStop Input

{
  hook_event_name: 'SubagentStop',
  session_id: string,
  stop_hook_active: boolean,
  cwd: string,
  transcript_path: string
}

Hook Integration Checklist

When creating hook-aware skills:

Identify which hook event(s) the skill responds to
Document the expected input schema from the hook
Define the response format the skill generates
Consider error cases and graceful degradation
Test with actual hook invocations if possible
Handle missing or malformed input gracefully
Return empty {} to allow operations by default

hook-integration