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