feat: add comprehensive analysis report for Hook templates compliance with official standards

- Introduced a detailed report outlining compliance issues and recommendations for the `ccw/frontend` implementation of Hook templates. - Identified critical issues regarding command structure and input reading methods. - Highlighted errors related to cross-platform compatibility of Bash scripts on Windows. - Documented warnings regarding matcher formats and exit code usage. - Provided a summary of supported trigger types and outlined missing triggers. - Included a section on completed fixes and references to affected files for easier tracking.
2026-03-02 15:23:19 +08:00 · 2026-03-01 15:12:44 +08:00
parent 8799a9c2fd
commit 9ad755e225
6 changed files with 819 additions and 59 deletions
--- a/ccw/frontend/src/components/hook/HookQuickTemplates.tsx
+++ b/ccw/frontend/src/components/hook/HookQuickTemplates.tsx
@@ -63,6 +63,8 @@ export interface HookQuickTemplatesProps {
 }

 // ========== Hook Templates ==========
+// NOTE: Hook input is received via stdin (not environment variable)
+// Use: const fs=require('fs');const p=JSON.parse(fs.readFileSync(0,'utf8')||'{}');

 /**
 * Predefined hook templates for quick installation
@@ -90,7 +92,7 @@ export const HOOK_TEMPLATES: readonly HookTemplate[] = [
    command: 'node',
    args: [
      '-e',
-      'const p=JSON.parse(process.env.HOOK_INPUT||"{}");const file=(p.tool_input&&p.tool_input.file_path)||"";if(/workflow-session\\.json$|session-metadata\\.json$/.test(file)){const fs=require("fs");try{const content=fs.readFileSync(file,"utf8");const data=JSON.parse(content);const cp=require("child_process");const payload=JSON.stringify({type:"SESSION_STATE_CHANGED",file:file,sessionId:data.session_id||"",status:data.status||"unknown",project:process.env.CLAUDE_PROJECT_DIR||process.cwd(),timestamp:Date.now()});cp.spawnSync("curl",["-s","-X","POST","-H","Content-Type: application/json","-d",payload,"http://localhost:3456/api/hook"],{stdio:"inherit",shell:true})}catch(e){}}'
+      'const fs=require("fs");const p=JSON.parse(fs.readFileSync(0,"utf8")||"{}");const file=(p.tool_input&&p.tool_input.file_path)||"";if(/workflow-session\\.json$|session-metadata\\.json$/.test(file)){try{const content=fs.readFileSync(file,"utf8");const data=JSON.parse(content);const cp=require("child_process");const payload=JSON.stringify({type:"SESSION_STATE_CHANGED",file:file,sessionId:data.session_id||"",status:data.status||"unknown",project:process.env.CLAUDE_PROJECT_DIR||process.cwd(),timestamp:Date.now()});cp.spawnSync("curl",["-s","-X","POST","-H","Content-Type: application/json","-d",payload,"http://localhost:3456/api/hook"],{stdio:"inherit",shell:true})}catch(e){}}'
    ]
  },
  // --- Notification ---
@@ -117,7 +119,7 @@ export const HOOK_TEMPLATES: readonly HookTemplate[] = [
    command: 'node',
    args: [
      '-e',
-      'const p=JSON.parse(process.env.HOOK_INPUT||"{}");const file=(p.tool_input&&p.tool_input.file_path)||"";if(file){const cp=require("child_process");cp.spawnSync("npx",["prettier","--write",file],{stdio:"inherit",shell:true})}'
+      'const fs=require("fs");const p=JSON.parse(fs.readFileSync(0,"utf8")||"{}");const file=(p.tool_input&&p.tool_input.file_path)||"";if(file){const cp=require("child_process");cp.spawnSync("npx",["prettier","--write",file],{stdio:"inherit",shell:true})}'
    ]
  },
  {
@@ -130,7 +132,7 @@ export const HOOK_TEMPLATES: readonly HookTemplate[] = [
    command: 'node',
    args: [
      '-e',
-      'const p=JSON.parse(process.env.HOOK_INPUT||"{}");const file=(p.tool_input&&p.tool_input.file_path)||"";if(file){const cp=require("child_process");cp.spawnSync("npx",["eslint","--fix",file],{stdio:"inherit",shell:true})}'
+      'const fs=require("fs");const p=JSON.parse(fs.readFileSync(0,"utf8")||"{}");const file=(p.tool_input&&p.tool_input.file_path)||"";if(file){const cp=require("child_process");cp.spawnSync("npx",["eslint","--fix",file],{stdio:"inherit",shell:true})}'
    ]
  },
  {
@@ -143,7 +145,7 @@ export const HOOK_TEMPLATES: readonly HookTemplate[] = [
    command: 'node',
    args: [
      '-e',
-      'const p=JSON.parse(process.env.HOOK_INPUT||"{}");const file=(p.tool_input&&p.tool_input.file_path)||"";if(/\\.env|secret|credential|\\.key$/.test(file)){process.stderr.write("Blocked: modifying sensitive file "+file);process.exit(2)}'
+      'const fs=require("fs");const p=JSON.parse(fs.readFileSync(0,"utf8")||"{}");const file=(p.tool_input&&p.tool_input.file_path)||"";if(/\\.env|secret|credential|\\.key$/.test(file)){process.stderr.write("Blocked: modifying sensitive file "+file);process.exit(2)}'
    ]
  },
  {
@@ -169,7 +171,7 @@ export const HOOK_TEMPLATES: readonly HookTemplate[] = [
    command: 'node',
    args: [
      '-e',
-      'const p=JSON.parse(process.env.HOOK_INPUT||"{}");const file=(p.tool_input&&p.tool_input.file_path)||"";if(file){const cp=require("child_process");const payload=JSON.stringify({type:"FILE_MODIFIED",file:file,project:process.env.CLAUDE_PROJECT_DIR||process.cwd(),timestamp:Date.now()});cp.spawnSync("curl",["-s","-X","POST","-H","Content-Type: application/json","-d",payload,"http://localhost:3456/api/hook"],{stdio:"inherit",shell:true})}'
+      'const fs=require("fs");const p=JSON.parse(fs.readFileSync(0,"utf8")||"{}");const file=(p.tool_input&&p.tool_input.file_path)||"";if(file){const cp=require("child_process");const payload=JSON.stringify({type:"FILE_MODIFIED",file:file,project:process.env.CLAUDE_PROJECT_DIR||process.cwd(),timestamp:Date.now()});cp.spawnSync("curl",["-s","-X","POST","-H","Content-Type: application/json","-d",payload,"http://localhost:3456/api/hook"],{stdio:"inherit",shell:true})}'
    ]
  },
  {
@@ -181,7 +183,7 @@ export const HOOK_TEMPLATES: readonly HookTemplate[] = [
    command: 'node',
    args: [
      '-e',
-      'const p=JSON.parse(process.env.HOOK_INPUT||"{}");const cp=require("child_process");const payload=JSON.stringify({type:"SESSION_SUMMARY",transcript:p.transcript_path||"",project:process.env.CLAUDE_PROJECT_DIR||process.cwd(),timestamp:Date.now()});cp.spawnSync("curl",["-s","-X","POST","-H","Content-Type: application/json","-d",payload,"http://localhost:3456/api/hook"],{stdio:"inherit",shell:true})'
+      'const fs=require("fs");const p=JSON.parse(fs.readFileSync(0,"utf8")||"{}");const cp=require("child_process");const payload=JSON.stringify({type:"SESSION_SUMMARY",transcript:p.transcript_path||"",project:process.env.CLAUDE_PROJECT_DIR||process.cwd(),timestamp:Date.now()});cp.spawnSync("curl",["-s","-X","POST","-H","Content-Type: application/json","-d",payload,"http://localhost:3456/api/hook"],{stdio:"inherit",shell:true})'
    ]
  },
  {
@@ -221,7 +223,7 @@ export const HOOK_TEMPLATES: readonly HookTemplate[] = [
    description: 'Sync memory V2 status to dashboard on changes',
    category: 'notification',
    trigger: 'PostToolUse',
-    matcher: 'core_memory',
+    matcher: 'mcp__ccw-tools__core_memory',
    command: 'node',
    args: [
      '-e',
--- a/ccw/frontend/src/components/hook/HookWizard.tsx
+++ b/ccw/frontend/src/components/hook/HookWizard.tsx
@@ -84,6 +84,9 @@ interface HookTemplate {
  timeout?: number;
 }

+// NOTE: Hook input is received via stdin (not environment variable)
+// Node.js: const fs=require('fs');const p=JSON.parse(fs.readFileSync(0,'utf8')||'{}');
+// Bash: INPUT=$(cat)
 const HOOK_TEMPLATES: Record<string, HookTemplate> = {
  'memory-update-queue': {
    event: 'Stop',
@@ -95,13 +98,13 @@ const HOOK_TEMPLATES: Record<string, HookTemplate> = {
    event: 'UserPromptSubmit',
    matcher: '',
    command: 'node',
-    args: ['-e', "const p=JSON.parse(process.env.HOOK_INPUT||'{}');require('child_process').spawnSync('ccw',['tool','exec','skill_context_loader',JSON.stringify({prompt:p.user_prompt||''})],{stdio:'inherit'})"],
+    args: ['-e', "const fs=require('fs');const p=JSON.parse(fs.readFileSync(0,'utf8')||'{}');require('child_process').spawnSync('ccw',['tool','exec','skill_context_loader',JSON.stringify({prompt:p.prompt||''})],{stdio:'inherit'})"],
  },
  'skill-context-auto': {
    event: 'UserPromptSubmit',
    matcher: '',
    command: 'node',
-    args: ['-e', "const p=JSON.parse(process.env.HOOK_INPUT||'{}');require('child_process').spawnSync('ccw',['tool','exec','skill_context_loader',JSON.stringify({mode:'auto',prompt:p.user_prompt||''})],{stdio:'inherit'})"],
+    args: ['-e', "const fs=require('fs');const p=JSON.parse(fs.readFileSync(0,'utf8')||'{}');require('child_process').spawnSync('ccw',['tool','exec','skill_context_loader',JSON.stringify({mode:'auto',prompt:p.prompt||''})],{stdio:'inherit'})"],
  },
  'danger-bash-confirm': {
    event: 'PreToolUse',
@@ -114,7 +117,7 @@ const HOOK_TEMPLATES: Record<string, HookTemplate> = {
    event: 'PreToolUse',
    matcher: 'Write|Edit',
    command: 'bash',
-    args: ['-c', 'INPUT=$(cat); FILE=$(echo "$INPUT" | jq -r ".tool_input.file_path // .tool_input.path // empty"); PROTECTED=".env|.git/|package-lock.json|yarn.lock|.credentials|secrets|id_rsa|.pem$|.key$"; if echo "$FILE" | grep -qiE "$PROTECTED"; then echo "{\\"hookSpecificOutput\\":{\\"hookEventName\\":\\"PreToolUse\\",\\"permissionDecision\\":\\"deny\\",\\"permissionDecisionReason\\":\\"Protected file cannot be modified: $FILE\\"}}" && exit 0; fi; exit 0'],
+    args: ['-c', 'INPUT=$(cat); FILE=$(echo "$INPUT" | jq -r ".tool_input.file_path // .tool_input.path // empty"); PROTECTED=".env|.git/|package-lock.json|yarn.lock|.credentials|secrets|id_rsa|.pem$|.key$"; if echo "$FILE" | grep -qiE "$PROTECTED"; then echo "{\\"hookSpecificOutput\\":{\\"hookEventName\\":\\"PreToolUse\\",\\"permissionDecision\\":\\"deny\\",\\"permissionDecisionReason\\":\\"Protected file cannot be modified: $FILE\\"}}" >&2 && exit 2; fi; exit 0'],
    timeout: 5000,
  },
  'danger-git-destructive': {
@@ -135,7 +138,7 @@ const HOOK_TEMPLATES: Record<string, HookTemplate> = {
    event: 'PreToolUse',
    matcher: 'Write|Edit|Bash',
    command: 'bash',
-    args: ['-c', 'INPUT=$(cat); TOOL=$(echo "$INPUT" | jq -r ".tool_name // empty"); if [ "$TOOL" = "Bash" ]; then CMD=$(echo "$INPUT" | jq -r ".tool_input.command // empty"); SYS_PATHS="/etc/|/usr/|/bin/|/sbin/|/boot/|/sys/|/proc/|C:\\\\Windows|C:\\\\Program Files"; if echo "$CMD" | grep -qiE "$SYS_PATHS"; then echo "{\\"hookSpecificOutput\\":{\\"hookEventName\\":\\"PreToolUse\\",\\"permissionDecision\\":\\"ask\\",\\"permissionDecisionReason\\":\\"System path operation requires confirmation\\"}}" && exit 0; fi; else FILE=$(echo "$INPUT" | jq -r ".tool_input.file_path // .tool_input.path // empty"); SYS_PATHS="/etc/|/usr/|/bin/|/sbin/|C:\\\\Windows|C:\\\\Program Files"; if echo "$FILE" | grep -qiE "$SYS_PATHS"; then echo "{\\"hookSpecificOutput\\":{\\"hookEventName\\":\\"PreToolUse\\",\\"permissionDecision\\":\\"deny\\",\\"permissionDecisionReason\\":\\"Cannot modify system file: $FILE\\"}}" && exit 0; fi; fi; exit 0'],
+    args: ['-c', 'INPUT=$(cat); TOOL=$(echo "$INPUT" | jq -r ".tool_name // empty"); if [ "$TOOL" = "Bash" ]; then CMD=$(echo "$INPUT" | jq -r ".tool_input.command // empty"); SYS_PATHS="/etc/|/usr/|/bin/|/sbin/|/boot/|/sys/|/proc/|C:\\\\Windows|C:\\\\Program Files"; if echo "$CMD" | grep -qiE "$SYS_PATHS"; then echo "{\\"hookSpecificOutput\\":{\\"hookEventName\\":\\"PreToolUse\\",\\"permissionDecision\\":\\"ask\\",\\"permissionDecisionReason\\":\\"System path operation requires confirmation\\"}}" && exit 0; fi; else FILE=$(echo "$INPUT" | jq -r ".tool_input.file_path // .tool_input.path // empty"); SYS_PATHS="/etc/|/usr/|/bin/|/sbin/|C:\\\\Windows|C:\\\\Program Files"; if echo "$FILE" | grep -qiE "$SYS_PATHS"; then echo "{\\"hookSpecificOutput\\":{\\"hookEventName\\":\\"PreToolUse\\",\\"permissionDecision\\":\\"deny\\",\\"permissionDecisionReason\\":\\"Cannot modify system file: $FILE\\"}}" >&2 && exit 2; fi; fi; exit 0'],
    timeout: 5000,
  },
  'danger-permission-change': {
--- a/ccw/src/core/routes/hooks-routes.ts
+++ b/ccw/src/core/routes/hooks-routes.ts
@@ -94,6 +94,75 @@ function getHooksConfig(projectPath: string): { global: { path: string; hooks: u
  };
 }

+/**
+ * Normalize hook data to Claude Code's official nested format
+ * Official format: { matcher?: string, hooks: [{ type: 'command', command: string, timeout?: number }] }
+ *
+ * IMPORTANT: All timeout values from frontend are in MILLISECONDS and must be converted to SECONDS.
+ * Official Claude Code spec requires timeout in seconds.
+ *
+ * @param {Object} hookData - Hook configuration (may be flat or nested format)
+ * @returns {Object} Normalized hook data in official format
+ */
+function normalizeHookFormat(hookData: Record<string, unknown>): Record<string, unknown> {
+  /**
+   * Convert timeout from milliseconds to seconds
+   * Frontend always sends milliseconds, Claude Code expects seconds
+   */
+  const convertTimeout = (timeout: number): number => {
+    // Always convert from milliseconds to seconds
+    // This is safe because:
+    // - Frontend (HookWizard) uses milliseconds (e.g., 5000ms)
+    // - Claude Code official spec requires seconds
+    // - Minimum valid timeout is 1 second, so any value < 1000ms becomes 1s
+    return Math.max(1, Math.ceil(timeout / 1000));
+  };
+
+  // If already in nested format with hooks array, validate and convert
+  if (hookData.hooks && Array.isArray(hookData.hooks)) {
+    // Ensure each hook in the array has required fields
+    const normalizedHooks = (hookData.hooks as Array<Record<string, unknown>>).map(h => {
+      const normalized: Record<string, unknown> = {
+        type: h.type || 'command',
+        command: h.command || '',
+      };
+      // Convert timeout from milliseconds to seconds
+      if (typeof h.timeout === 'number') {
+        normalized.timeout = convertTimeout(h.timeout);
+      }
+      return normalized;
+    });
+
+    return {
+      ...(hookData.matcher !== undefined ? { matcher: hookData.matcher } : { matcher: '' }),
+      hooks: normalizedHooks,
+    };
+  }
+
+  // Convert flat format to nested format
+  // Old format: { command: '...', timeout: 5000, name: '...', failMode: '...' }
+  // New format: { matcher: '', hooks: [{ type: 'command', command: '...', timeout: 5 }] }
+  if (hookData.command && typeof hookData.command === 'string') {
+    const nestedHook: Record<string, unknown> = {
+      type: 'command',
+      command: hookData.command,
+    };
+
+    // Convert timeout from milliseconds to seconds
+    if (typeof hookData.timeout === 'number') {
+      nestedHook.timeout = convertTimeout(hookData.timeout);
+    }
+
+    return {
+      matcher: typeof hookData.matcher === 'string' ? hookData.matcher : '',
+      hooks: [nestedHook],
+    };
+  }
+
+  // Return as-is if we can't normalize (let Claude Code validate)
+  return hookData;
+}
+
 /**
 * Save a hook to settings file
 * @param {string} projectPath
@@ -125,17 +194,19 @@ function saveHookToSettings(
      settings.hooks[event] = [settings.hooks[event]];
    }

+    // Normalize hook data to official format
+    const normalizedData = normalizeHookFormat(hookData);
+
    // Check if we're replacing an existing hook
    if (typeof hookData.replaceIndex === 'number') {
      const index = hookData.replaceIndex;
-      delete hookData.replaceIndex;
      const hooksForEvent = settings.hooks[event] as unknown[];
      if (index >= 0 && index < hooksForEvent.length) {
-        hooksForEvent[index] = hookData;
+        hooksForEvent[index] = normalizedData;
      }
    } else {
      // Add new hook
-      (settings.hooks[event] as unknown[]).push(hookData);
+      (settings.hooks[event] as unknown[]).push(normalizedData);
    }

    // Ensure directory exists and write file
--- a/ccw/src/core/routes/system-routes.ts
+++ b/ccw/src/core/routes/system-routes.ts
@@ -202,22 +202,27 @@ function installRecommendedHook(
      settings.hooks[event] = [];
    }

-    // Check if hook already exists (by command)
+    // Check if hook already exists (by command in nested hooks array)
    const existingHooks = (settings.hooks[event] || []) as Array<Record<string, unknown>>;
-    const existingIndex = existingHooks.findIndex(
-      (h) => (h as Record<string, unknown>).command === hook.command
-    );
+    const existingIndex = existingHooks.findIndex((entry) => {
+      const hooks = (entry as Record<string, unknown>).hooks as Array<Record<string, unknown>> | undefined;
+      if (!hooks || !Array.isArray(hooks)) return false;
+      return hooks.some((h) => (h as Record<string, unknown>).command === hook.command);
+    });

    if (existingIndex >= 0) {
      return { success: true, installed: { id: hookId, event, status: 'already-exists' } };
    }

-    // Add new hook
+    // Add new hook in Claude Code's official nested format
+    // Format: { matcher: '', hooks: [{ type: 'command', command: '...', timeout: 5 }] }
    settings.hooks[event].push({
-      name: hook.name,
-      command: hook.command,
-      timeout: 5000,
-      failMode: 'silent'
+      matcher: '',
+      hooks: [{
+        type: 'command',
+        command: hook.command,
+        timeout: 5  // seconds, not milliseconds
+      }]
    });

    // Ensure directory exists