Refactor error handling to use platform-specific worker restart instructions

- Updated multiple hooks (context-hook, new-hook, save-hook, summary-hook, user-message-hook) to throw errors using `getWorkerRestartInstructions` for improved user guidance on worker connection issues.
- Enhanced `handleWorkerError` function to utilize the new error message generator for consistent error reporting.
- Modified `ensureWorkerRunning` function to provide detailed instructions based on the worker's state, including port information.
- Introduced `getWorkerRestartInstructions` utility in `error-messages.ts` to generate platform-aware error messages for worker failures.

src/hooks/context-hook.ts

@@ -11,6 +11,7 @@ import { stdin } from "process";
 import { ensureWorkerRunning, getWorkerPort } from "../shared/worker-utils.js";
 import { HOOK_TIMEOUTS } from "../shared/hook-constants.js";
 import { handleWorkerError } from "../shared/hook-error-handler.js";
+import { getWorkerRestartInstructions } from "../utils/error-messages.js";
 
 export interface SessionStartInput {
   session_id: string;
@@ -34,7 +35,7 @@ async function contextHook(input?: SessionStartInput): Promise<string> {
 
     if (!response.ok) {
       const errorText = await response.text();
-      throw new Error(`Failed to fetch context: ${response.status} ${errorText}`);
+      throw new Error(getWorkerRestartInstructions({ includeSkillFallback: true }));
     }
 
     const result = await response.text();

src/hooks/new-hook.ts

@@ -4,6 +4,7 @@ import { createHookResponse } from './hook-response.js';
 import { ensureWorkerRunning, getWorkerPort } from '../shared/worker-utils.js';
 import { happy_path_error__with_fallback } from '../utils/silent-debug.js';
 import { handleWorkerError } from '../shared/hook-error-handler.js';
+import { getWorkerRestartInstructions } from '../utils/error-messages.js';
 
 export interface UserPromptSubmitInput {
   session_id: string;
@@ -52,7 +53,7 @@ async function newHook(input?: UserPromptSubmitInput): Promise<void> {
 
     if (!initResponse.ok) {
       const errorText = await initResponse.text();
-      throw new Error(`Failed to initialize session: ${initResponse.status} ${errorText}`);
+      throw new Error(getWorkerRestartInstructions({ includeSkillFallback: true }));
     }
 
     const initResult = await initResponse.json();
@@ -86,7 +87,7 @@ async function newHook(input?: UserPromptSubmitInput): Promise<void> {
 
     if (!response.ok) {
       const errorText = await response.text();
-      throw new Error(`Failed to start SDK agent: ${response.status} ${errorText}`);
+      throw new Error(getWorkerRestartInstructions({ includeSkillFallback: true }));
     }
   } catch (error: any) {
     handleWorkerError(error);

src/hooks/save-hook.ts

@@ -13,6 +13,7 @@ import { ensureWorkerRunning, getWorkerPort } from '../shared/worker-utils.js';
 import { HOOK_TIMEOUTS } from '../shared/hook-constants.js';
 import { happy_path_error__with_fallback } from '../utils/silent-debug.js';
 import { handleWorkerError } from '../shared/hook-error-handler.js';
+import { getWorkerRestartInstructions } from '../utils/error-messages.js';
 
 export interface PostToolUseInput {
   session_id: string;
@@ -67,7 +68,7 @@ async function saveHook(input?: PostToolUseInput): Promise<void> {
       logger.failure('HOOK', 'Failed to send observation', {
         status: response.status
       }, errorText);
-      throw new Error(`Failed to send observation to worker: ${response.status} ${errorText}`);
+      throw new Error(getWorkerRestartInstructions({ includeSkillFallback: true }));
     }
 
     logger.debug('HOOK', 'Observation sent successfully', { toolName: tool_name });

src/hooks/summary-hook.ts

@@ -17,6 +17,7 @@ import { HOOK_TIMEOUTS } from '../shared/hook-constants.js';
 import { happy_path_error__with_fallback } from '../utils/silent-debug.js';
 import { handleWorkerError } from '../shared/hook-error-handler.js';
 import { extractLastMessage } from '../shared/transcript-parser.js';
+import { getWorkerRestartInstructions } from '../utils/error-messages.js';
 
 export interface StopInput {
   session_id: string;
@@ -72,7 +73,7 @@ async function summaryHook(input?: StopInput): Promise<void> {
       logger.failure('HOOK', 'Failed to generate summary', {
         status: response.status
       }, errorText);
-      throw new Error(`Failed to request summary from worker: ${response.status} ${errorText}`);
+      throw new Error(getWorkerRestartInstructions({ includeSkillFallback: true }));
     }
 
     logger.debug('HOOK', 'Summary request sent successfully');

src/hooks/user-message-hook.ts

@@ -9,6 +9,7 @@
 import { basename } from "path";
 import { ensureWorkerRunning, getWorkerPort } from "../shared/worker-utils.js";
 import { HOOK_EXIT_CODES } from "../shared/hook-constants.js";
+import { getWorkerRestartInstructions } from "../utils/error-messages.js";
 
 try {
   // Ensure worker is running
@@ -24,7 +25,7 @@ try {
   );
 
   if (!response.ok) {
-    throw new Error(`Worker error ${response.status}`);
+    throw new Error(getWorkerRestartInstructions({ includeSkillFallback: true }));
   }
 
   const output = await response.text();