fix: update hook response types and improve command formatting

- Refactored PreToolUse and PostToolUse handlers to use more descriptive response types.
- Updated the handling of dangerous commands in PreToolUse to return a more informative response.
- Added a new SubagentStop handler for improved task management.
- Cleaned up formatting in init.ts for consistency.

This enhances type safety and clarity in the hook system.

Author: johnlindquist

CLAUDE.md

@@ -0,0 +1,69 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+### Building and Development
+- `bun run build` - Compile TypeScript to JavaScript
+- `bun run lint` - Run Biome linter
+- `bun run lint:fix` - Run Biome linter with auto-fix
+- `bun run format` - Format code with Biome
+
+### Testing
+- `bun test` - Run all tests
+- `bun run test:unit` - Run unit tests only
+- `bun run test:integration` - Run integration tests
+- `bun run test:smoke` - Run smoke tests
+- `bun run test:coverage` - Run tests with coverage report
+
+### Clean Up
+- `bun run clean` - Remove all build artifacts and test outputs
+- `bun run clean:test` - Remove only test output directories
+
+## Architecture
+
+This is an oclif-based CLI tool written in TypeScript that generates a hook system for Claude Code.
+
+### Key Components
+
+1. **Command Structure**: Commands live in `src/commands/`. Currently, there's only the main `init` command that sets up the hook system.
+
+2. **Template System**: Hook templates are stored in `templates/` and copied to the user's `.claude/` directory when initialized.
+
+3. **Hook Types**: The system supports four hook types:
+   - `PreToolUse` - Intercept tool usage before execution
+   - `PostToolUse` - React to tool execution results
+   - `Notification` - Handle Claude notifications
+   - `Stop` - Handle session stop events
+
+4. **Generated Structure**: Running the CLI creates:
+   ```
+   .claude/
+   ├── settings.json      # Hook configuration
+   └── hooks/
+       ├── index.ts       # Main hook handlers (user edits this)
+       ├── lib.ts         # Type definitions and utilities
+       └── session.ts     # Session tracking utilities
+   ```
+
+### Testing Strategy
+
+- **Unit Tests**: Test individual commands and components
+- **Integration Tests**: Test the full CLI behavior
+- **Smoke Tests**: Validate generated files work correctly
+- **CI/CD**: Tests run on Ubuntu, Windows, and macOS with Node 18 & 20
+
+### Development Workflow
+
+1. Work on feature branches, never directly on main
+2. Use conventional commits (e.g., `feat:`, `fix:`, `chore:`)
+3. Create pull requests to merge into main
+4. Semantic Release handles versioning and npm publishing automatically
+
+### Important Notes
+
+- Hooks are executed using Bun runtime (required dependency)
+- The project uses ESM modules (`"type": "module"`)
+- TypeScript strict mode is enabled
+- Session logs are written to the system temp directory

src/commands/init.ts

@@ -1,13 +1,10 @@
 import * as path from 'node:path'
-import {fileURLToPath} from 'node:url'
-import {Command, Flags} from '@oclif/core'
+import { fileURLToPath } from 'node:url'
+import { Command, Flags } from '@oclif/core'
 import chalk from 'chalk'
 import fs from 'fs-extra'
 import ora from 'ora'
 
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = path.dirname(__filename)
-
 export default class Init extends Command {
   static description = `Initialize Claude Code hooks in your project
 
@@ -37,16 +34,16 @@ This command sets up basic Claude Code hooks in your project:
   }
 
   public async run(): Promise<void> {
-    const {flags} = await this.parse(Init)
+    const { flags } = await this.parse(Init)
 
     console.log(chalk.blue.bold('\n🪝 Claude Hooks Setup\n'))
 
     // Check if Bun is installed
-    const {spawn} = await import('node:child_process')
+    const { spawn } = await import('node:child_process')
     const isWindows = process.platform === 'win32'
     const command = isWindows ? 'where' : 'which'
     const checkBun = await new Promise<boolean>((resolve) => {
-      const child = spawn(command, ['bun'], {shell: false})
+      const child = spawn(command, ['bun'], { shell: false })
       child.on('error', () => resolve(false))
       child.on('exit', (code) => resolve(code === 0))
     })

templates/hooks/index.ts

@@ -2,17 +2,18 @@
 
 import {
   type BashToolInput,
-  type HookResponse,
   type NotificationPayload,
   type PostToolUsePayload,
   type PreToolUsePayload,
+  type PreToolUseResponse,
   runHook,
   type StopPayload,
+  type SubagentStopPayload,
 } from './lib'
 import {saveSessionData} from './session'
 
 // PreToolUse handler - called before Claude uses any tool
-async function preToolUse(payload: PreToolUsePayload): Promise<HookResponse> {
+async function preToolUse(payload: PreToolUsePayload): Promise<PreToolUseResponse> {
   // Save session data (optional - remove if not needed)
   await saveSessionData('PreToolUse', payload)
 
@@ -31,14 +32,14 @@ async function preToolUse(payload: PreToolUsePayload): Promise<HookResponse> {
     // Block dangerous commands
     if (command.includes('rm -rf /') || command.includes('rm -rf ~')) {
       console.error('❌ Dangerous command detected! Blocking execution.')
-      return {action: 'reject', message: 'Dangerous command detected'}
+      return {decision: 'block', reason: `Dangerous command detected: ${command}`}
     }
   }
 
   // Add your custom logic here!
   // You have full TypeScript support and can use any npm packages
 
-  return {action: 'continue'}
+  return {} // Empty object means continue with default behavior
 }
 
 // PostToolUse handler - called after Claude uses a tool
@@ -47,7 +48,7 @@ async function postToolUse(payload: PostToolUsePayload): Promise<void> {
   await saveSessionData('PostToolUse', payload)
 
   // Example: React to successful file writes
-  if (payload.tool_name === 'Write' && payload.success) {
+  if (payload.tool_name === 'Write' && payload.tool_response) {
     console.log(`✅ File written successfully!`)
   }
 
@@ -67,7 +68,21 @@ async function stop(payload: StopPayload): Promise<void> {
   await saveSessionData('Stop', payload)
 
   // Example: Summary or cleanup logic
-  console.log(`👋 Session ended: ${payload.reason}`)
+  console.log(`👋 Session ended`)
+}
+
+// SubagentStop handler - called when a Claude subagent (Task tool) stops
+async function subagentStop(payload: SubagentStopPayload): Promise<void> {
+  await saveSessionData('SubagentStop', payload)
+
+  // Example: Log subagent completion
+  console.log(`🤖 Subagent task completed`)
+
+  // Add your custom subagent cleanup logic here
+  // Note: Be careful with stop_hook_active to avoid infinite loops
+  if (payload.stop_hook_active) {
+    console.log('⚠️  Stop hook is already active, skipping additional processing')
+  }
 }
 
 // Run the hook with our handlers
@@ -76,4 +91,5 @@ runHook({
   postToolUse,
   notification,
   stop,
+  subagentStop,
 })

templates/hooks/lib.ts

@@ -3,37 +3,76 @@
 import * as fs from 'node:fs/promises'
 import * as path from 'node:path'
 
-// Types
+// Input payload types based on official Claude Code schemas
 export interface PreToolUsePayload {
-  hook_type: 'PreToolUse'
   session_id: string
+  transcript_path: string
   tool_name: string
   tool_input: Record<string, any>
 }
 
 export interface PostToolUsePayload {
-  hook_type: 'PostToolUse'
   session_id: string
+  transcript_path: string
   tool_name: string
   tool_input: Record<string, any>
-  tool_result: any
-  tool_error: string | null
+  tool_response: Record<string, any> & {
+    success?: boolean
+  }
 }
 
 export interface NotificationPayload {
-  hook_type: 'Notification'
   session_id: string
+  transcript_path: string
   message: string
-  level: 'info' | 'warning' | 'error'
+  title: string
 }
 
 export interface StopPayload {
-  hook_type: 'Stop'
   session_id: string
+  transcript_path: string
+  stop_hook_active: boolean
 }
 
-export type HookPayload = PreToolUsePayload | PostToolUsePayload | NotificationPayload | StopPayload
+export interface SubagentStopPayload {
+  session_id: string
+  transcript_path: string
+  stop_hook_active: boolean
+}
+
+export type HookPayload =
+  | (PreToolUsePayload & {hook_type: 'PreToolUse'})
+  | (PostToolUsePayload & {hook_type: 'PostToolUse'})
+  | (NotificationPayload & {hook_type: 'Notification'})
+  | (StopPayload & {hook_type: 'Stop'})
+  | (SubagentStopPayload & {hook_type: 'SubagentStop'})
+
+// Base response fields available to all hooks
+export interface BaseHookResponse {
+  continue?: boolean
+  stopReason?: string
+  suppressOutput?: boolean
+}
+
+// PreToolUse specific response
+export interface PreToolUseResponse extends BaseHookResponse {
+  decision?: 'approve' | 'block'
+  reason?: string
+}
 
+// PostToolUse specific response
+export interface PostToolUseResponse extends BaseHookResponse {
+  decision?: 'block'
+  reason?: string
+}
+
+// Stop/SubagentStop specific response
+export interface StopResponse extends BaseHookResponse {
+  decision?: 'block'
+  reason?: string // Required when decision is 'block'
+}
+
+// Legacy simple response for backward compatibility
 export interface HookResponse {
   action: 'continue' | 'block'
   stopReason?: string
@@ -46,16 +85,18 @@ export interface BashToolInput {
 }
 
 // Hook handler types
-export type PreToolUseHandler = (payload: PreToolUsePayload) => Promise<HookResponse> | HookResponse
+export type PreToolUseHandler = (payload: PreToolUsePayload) => Promise<PreToolUseResponse> | PreToolUseResponse
 export type PostToolUseHandler = (payload: PostToolUsePayload) => Promise<void> | void
 export type NotificationHandler = (payload: NotificationPayload) => Promise<void> | void
 export type StopHandler = (payload: StopPayload) => Promise<void> | void
+export type SubagentStopHandler = (payload: SubagentStopPayload) => Promise<void> | void
 
 export interface HookHandlers {
   preToolUse?: PreToolUseHandler
   postToolUse?: PostToolUseHandler
   notification?: NotificationHandler
   stop?: StopHandler
+  subagentStop?: SubagentStopHandler
 }
 
 // Session management utilities
@@ -106,45 +147,54 @@ export function runHook(handlers: HookHandlers): void {
   process.stdin.on('data', async (data) => {
     try {
       const inputData = JSON.parse(data.toString())
+      // Add hook_type for internal processing (not part of official input schema)
       const payload: HookPayload = {
         ...inputData,
         hook_type: hook_type as any,
       }
 
-      switch (hook_type) {
+      switch (payload.hook_type) {
         case 'PreToolUse':
           if (handlers.preToolUse) {
             const response = await handlers.preToolUse(payload)
             console.log(JSON.stringify(response))
           } else {
-            console.log(JSON.stringify({action: 'continue'}))
+            console.log(JSON.stringify({}))
           }
           break
 
         case 'PostToolUse':
           if (handlers.postToolUse) {
             await handlers.postToolUse(payload)
           }
-          console.log(JSON.stringify({action: 'continue'}))
+          console.log(JSON.stringify({}))
           break
 
         case 'Notification':
           if (handlers.notification) {
             await handlers.notification(payload)
           }
-          console.log(JSON.stringify({action: 'continue'}))
+          console.log(JSON.stringify({}))
           break
 
         case 'Stop':
           if (handlers.stop) {
             await handlers.stop(payload)
           }
-          console.log(JSON.stringify({action: 'continue'}))
+          console.log(JSON.stringify({}))
           process.exit(0)
-          break
+          return // Unreachable but satisfies linter
+
+        case 'SubagentStop':
+          if (handlers.subagentStop) {
+            await handlers.subagentStop(payload)
+          }
+          console.log(JSON.stringify({}))
+          process.exit(0)
+          return // Unreachable but satisfies linter
 
         default:
-          console.log(JSON.stringify({action: 'continue'}))
+          console.log(JSON.stringify({}))
       }
     } catch (error) {
       console.error('Hook error:', error)