feat: add default sessionStart handler to template (#51)

Author: johnlindquist

add-session-start.sed

@@ -0,0 +1,54 @@
+#!/bin/sed -f
+
+# Add SessionStartPayload interface after PreCompactPayload
+/^}$/,/^export type HookPayload/ {
+  /^export type HookPayload/ i\
+\
+export interface SessionStartPayload {\
+  session_id: string\
+  transcript_path: string\
+  hook_event_name: 'SessionStart'\
+  source: string\
+}
+}
+
+# Add SessionStart to HookPayload union type
+/| (PreCompactPayload & {hook_type: 'PreCompact'})$/ a\
+  | (SessionStartPayload & {hook_type: 'SessionStart'})
+
+# Add SessionStartResponse interface after PreCompactResponse
+/^}$/,/^\/\/ Legacy simple response/ {
+  /^\/\/ Legacy simple response/ i\
+\
+// SessionStart specific response\
+export interface SessionStartResponse extends BaseHookResponse {\
+  decision?: 'approve' | 'block'\
+  reason?: string\
+  hookSpecificOutput?: {\
+    hookEventName: 'SessionStart'\
+    additionalContext?: string\
+  }\
+}
+}
+
+# Add SessionStartHandler type after PreCompactHandler
+/^export type PreCompactHandler.*$/ a\
+export type SessionStartHandler = (payload: SessionStartPayload) => Promise<SessionStartResponse> | SessionStartResponse
+
+# Add sessionStart to HookHandlers interface
+/  preCompact\?: PreCompactHandler$/ a\
+  sessionStart?: SessionStartHandler
+
+# Add SessionStart case in runHook switch statement
+/case 'PreCompact':.*$/,/break$/ {
+  /break$/ a\
+\
+      case 'SessionStart':\
+        if (handlers.sessionStart) {\
+          const response = await handlers.sessionStart(payload)\
+          console.log(JSON.stringify(response))\
+        } else {\
+          console.log(JSON.stringify({}))\
+        }\
+        break
+}

templates/hooks/index.ts

@@ -5,13 +5,41 @@ import type {
   PostToolUseHandler,
   PreCompactHandler,
   PreToolUseHandler,
+  SessionStartHandler,
   StopHandler,
   SubagentStopHandler,
   UserPromptSubmitHandler,
 } from './lib'
 import {runHook} from './lib'
 import {saveSessionData} from './session'
 
+// SessionStart handler - called when a new Claude session starts
+const sessionStart: SessionStartHandler = async (payload) => {
+  // Save session data (optional - remove if not needed)
+  await saveSessionData('SessionStart', {...payload, hook_type: 'SessionStart'} as const)
+
+  // Example: Log session start with source
+  console.log(`🚀 New session started from: ${payload.source}`)
+  console.log(`📍 Session ID: ${payload.session_id}`)
+
+  // Example: Load user preferences or configuration
+  // const userConfig = await loadUserPreferences()
+
+  // Example: Set up session-specific resources
+  // await initializeSessionResources(payload.session_id)
+
+  // Example: Apply different behavior based on session source
+  if (payload.source === 'vscode') {
+    console.log('👨‍💻 VS Code session detected - enabling IDE-specific features')
+  } else if (payload.source === 'web') {
+    console.log('🌐 Web session detected')
+  }
+
+  // Add your custom session initialization logic here
+
+  return {} // Empty object means continue normally
+}
+
 // PreToolUse handler - called before Claude uses any tool
 // This handler can block tool execution by returning a deny decision
 const preToolUse: PreToolUseHandler = async (payload) => {
@@ -143,6 +171,7 @@ const preCompact: PreCompactHandler = async (payload) => {
 
 // Run the hook with our handlers
 runHook({
+  sessionStart,
   preToolUse,
   postToolUse,
   notification,