@hailer/mcp 1.0.29 → 1.1.2

package/.claude/hooks/delegation-reminder.cjs

@@ -0,0 +1,478 @@
+#!/usr/bin/env node
+/**
+ * <hook-name>delegation-reminder</hook-name>
+ * <purpose>Enforces delegation pattern - orchestrator should delegate, not do directly</purpose>
+ * <triggers>PreToolUse</triggers>
+ *
+ * delegation-reminder.cjs
+ *
+ * HARD BLOCKS (data safety - writes only):
+ * - MCP write tools: create_activity, update_activity → Dmitri
+ * - install_workflow → Helga (use SDK)
+ *
+ * SOFT SUGGESTIONS (allows but reminds - specialists may need direct access):
+ * - MCP read tools: list_activities, get_workflow_schema, etc. → appropriate specialist
+ * - workspace/ reads → Kenji (but Helga/Viktor/Alejandro/Ingrid need access too)
+ * - Glob/Grep code searches → Explore agent
+ * - Task(giuseppe) for new app: Suggest ui-designer first
+ * - Task(giuseppe) for demo/mockup: Suggest marco-mockup instead
+ * - workspace/ writes: Suggest Helga
+ * - apps/ files: Suggest Giuseppe
+ * - .claude/agents/: Suggest Builder
+ * - .claude/skills/: Suggest Ada
+ * - git commit: Suggest Svetlana for review
+ * - After .ts/.tsx edits: Suggest Tanya for tests
+ *
+ * SILENTLY ALLOWS:
+ * - Schema/list tools used by multiple specialists (get_workflow_schema, list_workflows, etc.)
+ *
+ * SKIPS:
+ * - When called from within a subagent (checks agent stack + env vars)
+ *
+ * NOTE: Delegation is enforced even in yolo mode. Yolo only bypasses confirmation
+ * prompts (bulk-activity-guard, destructive-command-guard), not delegation pattern.
+ *
+ * Hook type: PreToolUse
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Cross-platform temp directory
+const TEMP_DIR = os.tmpdir();
+
+// Agent stack file maintained by builder-mode-manager.cjs
+const AGENT_STACK_FILE = path.join(TEMP_DIR, '.claude-agent-stack.json');
+
+/**
+ * Check if we're running inside a subagent.
+ * Uses multiple detection methods:
+ * 1. Agent stack file (maintained by builder-mode-manager.cjs)
+ * 2. CLAUDE_SUBAGENT environment variable (set by Claude Code Task tool)
+ * 3. CLAUDE_AGENT_* environment variables (agent identity markers)
+ */
+function isInsideSubagent() {
+  // Method 1: Check agent stack file
+  try {
+    const stack = JSON.parse(fs.readFileSync(AGENT_STACK_FILE, 'utf8'));
+    if (stack.agents && stack.agents.length > 0) {
+      return true;
+    }
+  } catch (e) {
+    // File doesn't exist or invalid JSON - continue to other methods
+  }
+
+  // Method 2: Check CLAUDE_SUBAGENT env var (may be set by Task tool)
+  if (process.env.CLAUDE_SUBAGENT === 'true' || process.env.CLAUDE_SUBAGENT === '1') {
+    return true;
+  }
+
+  // Method 3: Check for agent identity markers in environment
+  // When Task tool spawns a subagent, certain env vars may be present
+  if (process.env.CLAUDE_AGENT_TYPE || process.env.CLAUDE_AGENT_ID) {
+    return true;
+  }
+
+  return false;
+}
+
+// Tool -> Agent mappings
+const MCP_TOOL_AGENTS = {
+  // Kenji - data reader
+  'mcp__hailer__list_activities': 'agent-kenji-data-reader',
+  'mcp__hailer__count_activities': 'agent-kenji-data-reader',
+  'mcp__hailer__get_activity': 'agent-kenji-data-reader',
+  'mcp__hailer__list_workflows': 'agent-kenji-data-reader',
+  'mcp__hailer__list_workflows_minimal': 'agent-kenji-data-reader',
+  'mcp__hailer__get_workflow_schema': 'agent-kenji-data-reader',
+  'mcp__hailer__list_workflow_phases': 'agent-kenji-data-reader',
+
+  // Dmitri - activity CRUD
+  'mcp__hailer__create_activity': 'agent-dmitri-activity-crud',
+  'mcp__hailer__update_activity': 'agent-dmitri-activity-crud',
+
+  // Viktor - insights
+  'mcp__hailer__preview_insight': 'agent-viktor-sql-insights',
+  'mcp__hailer__get_insight_data': 'agent-viktor-sql-insights',
+  'mcp__hailer__list_insights': 'agent-viktor-sql-insights',
+
+  // Yevgeni - discussions
+  'mcp__hailer__list_my_discussions': 'agent-yevgeni-discussions',
+  'mcp__hailer__fetch_discussion_messages': 'agent-yevgeni-discussions',
+  'mcp__hailer__add_discussion_message': 'agent-yevgeni-discussions',
+  'mcp__hailer__join_discussion': 'agent-yevgeni-discussions',
+  'mcp__hailer__leave_discussion': 'agent-yevgeni-discussions',
+  'mcp__hailer__invite_discussion_members': 'agent-yevgeni-discussions',
+
+  // Permissions
+  'mcp__hailer__list_apps': 'agent-permissions-handler',
+  'mcp__hailer__add_app_member': 'agent-permissions-handler',
+  'mcp__hailer__remove_app_member': 'agent-permissions-handler',
+  'mcp__hailer__search_workspace_users': 'agent-permissions-handler',
+
+  // Giuseppe - app scaffold and local dev
+  'mcp__hailer__scaffold_hailer_app': 'agent-giuseppe-app-builder',
+  'mcp__hailer__create_app': 'agent-giuseppe-app-builder',
+
+  // Helga - workflow config (use SDK, not MCP)
+  'mcp__hailer__install_workflow': 'agent-helga-workflow-config',
+  'mcp__hailer__create_workflow': 'agent-helga-workflow-config',
+  'mcp__hailer__update_workflow': 'agent-helga-workflow-config',
+  'mcp__hailer__delete_workflow': 'agent-helga-workflow-config',
+};
+
+// File patterns that suggest delegation
+const FILE_PATTERN_AGENTS = {
+  'workspace/': 'agent-kenji-data-reader',
+  '/workspace/': 'agent-kenji-data-reader',
+  'apps/': 'agent-giuseppe-app-builder',
+  '/apps/': 'agent-giuseppe-app-builder',
+  '.claude/agents/': 'agent-builder-agent-creator',
+  '.claude/skills/': 'agent-ada-skill-builder',
+};
+
+// Check yolo mode once at startup
+let _isYolo = false;
+try {
+  const statePath = path.join(process.env.CLAUDE_PROJECT_DIR || process.cwd(), '.claude', 'yolo-state.json');
+  const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+  _isYolo = state.mode === 'yolo';
+} catch {}
+
+/**
+ * In normal mode: soft suggestion (allow + message)
+ * In yolo mode: hard block (force delegation)
+ *
+ * Yolo means "autonomous via agents", not "orchestrator does everything".
+ */
+function suggest(message, agentHint) {
+  if (_isYolo) {
+    console.log(JSON.stringify({
+      decision: "block",
+      reason: `🚫 YOLO DELEGATION: In autonomous mode, delegate to agents.\n\n${message}${agentHint ? `\n\nDelegate to: ${agentHint}` : ''}`,
+    }));
+  } else {
+    console.log(JSON.stringify({
+      decision: "allow",
+      message: message,
+    }));
+  }
+}
+
+// Read stdin asynchronously for better cross-platform support
+let stdinData = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => stdinData += chunk);
+process.stdin.on('end', () => {
+  try {
+    const input = JSON.parse(stdinData);
+    processInput(input);
+  } catch (e) {
+    console.error(`[delegation-reminder] Failed to parse input: ${e.message}`);
+    console.log(JSON.stringify({ decision: 'allow' }));
+    process.exit(0);
+  }
+});
+
+// Check if stdin is TTY (no piped input)
+if (process.stdin.isTTY) {
+  console.log(JSON.stringify({ decision: 'allow' }));
+  process.exit(0);
+}
+
+function processInput(input) {
+  const { tool_name, tool_input } = input;
+
+  // Skip if running inside a subagent (check agent stack, not env var)
+  if (isInsideSubagent()) {
+    console.log(JSON.stringify({ decision: "allow" }));
+    return;
+  }
+
+  // WORKFLOW SUGGESTIONS: Task tool spawning
+  if (tool_name === 'Task') {
+    const agentType = tool_input?.subagent_type || '';
+    // ReDoS protection: limit prompt size before regex matching
+    let prompt = (tool_input?.prompt || '').toLowerCase();
+    if (prompt.length > 10000) prompt = prompt.substring(0, 10000);
+
+    // HARD BLOCK: Built-in agent types - use specialized agents instead
+    // Built-in agents lack Skill tool and specialized domain knowledge
+    const BUILTIN_AGENTS = {
+      'Plan': 'Agents should plan their own work. Give the executing agent a prompt that includes research + planning + implementation. E.g., Ingrid can load SDK-document-templates skill and plan the template herself.',
+      'general-purpose': 'Use the appropriate specialized agent. Check /help:agents for the right one.',
+      'Bash': 'Run bash commands directly with the Bash tool instead of spawning a Bash agent.',
+    };
+
+    if (BUILTIN_AGENTS[agentType]) {
+      console.log(JSON.stringify({
+        decision: "block",
+        reason: `🚫 BUILT-IN AGENT BLOCKED: "${agentType}" is a Claude Code built-in agent. Use specialized agents instead.\n\n${BUILTIN_AGENTS[agentType]}\n\nAgents should do their own planning+research+execution. Include research steps in the agent's prompt instead of splitting into separate Plan/Explore agents.`,
+      }));
+      return;
+    }
+
+    // Giuseppe for new app - suggest ui-designer first
+    if (agentType.includes('giuseppe')) {
+      // Check if it's a demo/mockup request - use word boundaries to avoid false positives
+      if (/\b(demo|mockup|prototype)\b/i.test(prompt) ||
+          ((/\b(show|present)\b/i.test(prompt)) &&
+           (/\b(customer|client|stakeholder)\b/i.test(prompt)))) {
+        console.log(JSON.stringify({
+          decision: "allow",
+          message: `💡 FOR DEMOS: Consider using agent-marco-mockup-builder instead.\n\nMarco creates interactive demos with mock data - perfect for showing customers concepts.\nGiuseppe builds production apps.\n\nUse marco for: demos, prototypes, "what if" explorations\nUse giuseppe for: real apps with SDK integration`,
+        }));
+        return;
+      }
+
+      // Check if design was mentioned
+      if (!prompt.includes('design') && !prompt.includes('spec') && !prompt.includes('following the design')) {
+        console.log(JSON.stringify({
+          decision: "allow",
+          message: `💡 APP WORKFLOW: Consider the full flow:\n\n1. Plan Mode → understand requirements\n2. ui-designer → create design spec\n3. Giuseppe → build the app\n\nIf you haven't created a design spec yet, consider:\nTask(subagent_type="ui-designer", prompt='{"task":"design_app","requirements":"..."}')`,
+        }));
+        return;
+      }
+    }
+  }
+
+  // SUGGEST: Git commit - run tests and code review first
+  if (tool_name === 'Bash') {
+    const command = tool_input?.command || '';
+
+    if (command.includes('git commit')) {
+      console.log(JSON.stringify({
+        decision: "allow",
+        message: `💡 BEFORE COMMIT: Consider running tests and code review.\n\n1. Task(subagent_type="agent-tanya-test-runner", prompt='{"task":"run_tests"}')\n2. Task(subagent_type="agent-svetlana-code-review", prompt='{"task":"review_changes"}')\n\nTanya runs tests, Svetlana checks for bugs and security issues.`,
+      }));
+      return;
+    }
+
+    // Suggest tests after build passes
+    if (command.includes('npm run build') && !command.includes('test')) {
+      console.log(JSON.stringify({
+        decision: "allow",
+        message: `💡 BUILD PASSED? Consider running tests.\n\nTask(subagent_type="agent-tanya-test-runner", prompt='{"task":"run_tests"}')\n\nTanya runs vitest/playwright and reports failures.`,
+      }));
+      return;
+    }
+  }
+
+  // SOFT SUGGEST: Glob/Grep code searches - always soft (orchestrator needs these for delegation)
+  // These are orchestration tools, not domain work - never block even in yolo
+  if (tool_name === 'Glob' || tool_name === 'Grep') {
+    console.log(JSON.stringify({
+      decision: "allow",
+      message: `💡 CODE SEARCH: For workspace/schema searches, delegate to Kenji.\nFor broader research, include search instructions in the appropriate agent's prompt.\n\n(Specialist agents may search within their domains - this is just a reminder.)`,
+    }));
+    return;
+  }
+
+  // SUGGEST: Web search - delegate to save context (always soft - orchestrator may need quick lookups)
+  if (tool_name === 'WebSearch' || tool_name === 'WebFetch') {
+    console.log(JSON.stringify({
+      decision: "allow",
+      message: `💡 SAVE CONTEXT: Consider delegating web research to agent-web-search.\n\nThe agent searches, fetches pages, and returns concise summaries instead of dumping raw content.\n\nTask(subagent_type="agent-web-search", prompt='{"query":"your question","context":"optional background"}')`,
+    }));
+    return;
+  }
+
+  // MCP tools - block writes, suggest for reads
+  if (tool_name?.startsWith('mcp__hailer__')) {
+    // HARD BLOCK: install_workflow should use SDK, not MCP
+    // Enforced even in yolo mode - delegation is about correctness, not permissions
+    if (tool_name === 'mcp__hailer__install_workflow') {
+      console.log(JSON.stringify({
+        decision: "block",
+        reason: `🚫 USE SDK, NOT MCP: For workflow creation, use agent-helga-workflow-config with the SDK approach.
+
+Helga manages workflows via workspace/ files + npm commands, not MCP tools.
+
+Task(subagent_type="agent-helga-workflow-config", prompt='{"task":"create_workflow","name":"MyWorkflow","description":"..."}')
+
+The install_workflow MCP tool is for admin/dev use only.`,
+      }));
+      return;
+    }
+
+    // HARD BLOCK: Activity writes must go through Dmitri
+    // Enforced even in yolo mode - Dmitri validates field formats
+    if (tool_name === 'mcp__hailer__create_activity' || tool_name === 'mcp__hailer__update_activity') {
+      console.log(JSON.stringify({
+        decision: "block",
+        reason: `🚫 DELEGATE TO DMITRI: Activity writes must go through agent-dmitri-activity-crud.
+
+Dmitri validates:
+- Required fields are provided
+- Field value formats (activitylink=string, date=timestamp)
+- Real MongoDB ObjectIds (not SDK enums)
+
+Task(subagent_type="agent-dmitri-activity-crud", prompt='{"task":"create","workflow_id":"...","phase_id":"...","activities":[...]}')`,
+      }));
+      return;
+    }
+
+    // MCP READ TOOLS: Always allow with soft message (never block, even in yolo)
+    // Subagent detection is unreliable — we can't tell if Viktor or the orchestrator
+    // is calling preview_insight. Blocking would break agents using their own tools.
+    const suggestedAgent = MCP_TOOL_AGENTS[tool_name];
+    if (suggestedAgent) {
+      // Skip suggestion for tools that multiple agents legitimately use
+      const multiAgentTools = [
+        'mcp__hailer__get_workflow_schema',
+        'mcp__hailer__list_workflows',
+        'mcp__hailer__list_workflows_minimal',
+        'mcp__hailer__list_workflow_phases',
+      ];
+
+      if (multiAgentTools.includes(tool_name)) {
+        console.log(JSON.stringify({ decision: "allow" }));
+        return;
+      }
+
+      // Always allow — agents need their own tools
+      // (Viktor→preview_insight, Kenji→list_activities, etc.)
+      console.log(JSON.stringify({
+        decision: "allow",
+        message: `💡 MCP TOOL: If you're the orchestrator, consider delegating to ${suggestedAgent}.`,
+      }));
+      return;
+    }
+
+    // Unknown MCP tool - allow with reminder
+    console.log(JSON.stringify({
+      decision: "allow",
+      message: `💡 DELEGATE: Consider /help:agents for the right agent. Tool: ${tool_name}`,
+    }));
+    return;
+  }
+
+  // BLOCK: Reading workspace/ - must delegate to Kenji (with bypass option)
+  if (tool_name === 'Read') {
+    const filePath = tool_input?.file_path || '';
+
+    // workspace/ reads - SOFT SUGGESTION (not blocking)
+    // Multiple specialist agents (Helga, Viktor, Alejandro, Ingrid) need workspace access
+    // Subagent detection isn't reliable, so we suggest rather than block
+    if (filePath.includes('workspace/') || filePath.includes('/workspace/')) {
+      suggest(`💡 WORKSPACE READ: If you're the orchestrator, consider delegating to Kenji.\n\nTask(subagent_type="agent-kenji-data-reader", prompt='{"task":"read_workspace_file","path":"${filePath}"}')\n\n(Specialist agents like Helga/Viktor need direct access - this is just a reminder.)`, 'agent-kenji-data-reader');
+      return;
+    }
+
+    // Other file patterns - soft suggestions
+    for (const [pattern, agent] of Object.entries(FILE_PATTERN_AGENTS)) {
+      if (filePath.includes(pattern) && !pattern.includes('workspace')) {
+        const suggestions = {
+          'apps/': 'Giuseppe builds and maintains apps. Consider delegating app work.',
+          '.claude/agents/': 'Use agent-builder-agent-creator for creating/modifying agents.',
+          '.claude/skills/': 'Use agent-ada-skill-builder for creating/modifying skills.',
+        };
+        const suggestion = suggestions[pattern];
+        if (suggestion) {
+          suggest(`💡 CONSIDER DELEGATING: ${suggestion}\n\nAgent: ${agent}`, agent);
+          return;
+        }
+      }
+    }
+  }
+
+  // SOFT REMIND: Write/Edit on various files
+  if (tool_name === 'Write' || tool_name === 'Edit') {
+    const filePath = tool_input?.file_path || '';
+
+    // WORKSPACE WRITES: Suggest appropriate specialist
+    if (filePath.includes('workspace/')) {
+      // Function field code
+      if (filePath.includes('/functions/')) {
+        suggest(`💡 FUNCTION FIELD CODE: Use agent-alejandro-function-fields.\n\nAlejandro specializes in calculated fields, functionVariables, and JavaScript formulas.`, 'agent-alejandro-function-fields');
+        return;
+      }
+
+      // fields.ts - could involve function fields
+      if (filePath.includes('fields.ts')) {
+        suggest(`💡 FIELD DEFINITIONS: Use agent-helga-workflow-config for field config.\n\n💡 FOR FUNCTION FIELDS: If adding functionEnabled/functionVariables, also use agent-alejandro-function-fields for the function code.\n\nWorkflow: Helga adds field config → Alejandro writes function code`, 'agent-helga-workflow-config');
+        return;
+      }
+
+      // Document templates
+      if (filePath.includes('/templates/')) {
+        suggest(`💡 DOCUMENT TEMPLATES: Use agent-ingrid-doc-templates.\n\nIngrid handles PDF/CSV templates, pdfmake structure, and field mappings.`, 'agent-ingrid-doc-templates');
+        return;
+      }
+
+      // Insights
+      if (filePath.includes('insights.ts')) {
+        suggest(`💡 INSIGHTS: Use agent-viktor-sql-insights.\n\nViktor creates SQL queries, data sources, and insight configurations.`, 'agent-viktor-sql-insights');
+        return;
+      }
+
+      // General workspace config
+      suggest(`💡 WORKSPACE CONFIG: Use agent-helga-workflow-config.\n\nHelga manages workflows, fields, phases via SDK. Knows correct field types and push/pull order.`, 'agent-helga-workflow-config');
+      return;
+    }
+
+    // Suggest delegation for agent/skill modifications
+    if (filePath.includes('.claude/agents/')) {
+      suggest(`💡 CONSIDER DELEGATING: Use agent-builder-agent-creator for agent modifications.\n\nIt follows agent structure patterns and validates format.`, 'agent-builder-agent-creator');
+      return;
+    }
+
+    if (filePath.includes('.claude/skills/')) {
+      suggest(`💡 CONSIDER DELEGATING: Use agent-ada-skill-builder for skill modifications.\n\nIt creates skills from patterns and failure analysis.`, 'agent-ada-skill-builder');
+      return;
+    }
+
+    // .claude/ config files - allow in yolo (orchestrator legitimately edits config)
+    if (filePath.includes('.claude/') && (filePath.endsWith('.json') || filePath.endsWith('.cjs'))) {
+      console.log(JSON.stringify({
+        decision: "allow",
+        message: `💡 CONFIG CHANGE: After editing .claude/ config, consider running audit.\n\nTask(subagent_type="agent-bjorn-config-audit", prompt='{"task":"audit_config"}')`,
+      }));
+      return;
+    }
+
+    if (filePath.includes('apps/') && (filePath.endsWith('.tsx') || filePath.endsWith('.ts'))) {
+      suggest(`💡 CONSIDER DELEGATING: Use agent-giuseppe-app-builder for app code.\n\nGiuseppe handles SDK patterns, design system, and build verification.`, 'agent-giuseppe-app-builder');
+      return;
+    }
+
+    // Integration files
+    if (filePath.includes('integrations/') || filePath.includes('activity-mover')) {
+      suggest(`💡 INTEGRATIONS: Consider the specialist:\n\n- agent-igor-activity-mover-automation: Phase cascade bots\n- agent-ivan-monolith: Webhook handlers, scheduled jobs\n- agent-zara-zapier: Zapier integrations`);
+      return;
+    }
+
+    // General .ts/.tsx code edits - don't block in yolo, just remind about tests
+    if ((filePath.endsWith('.ts') || filePath.endsWith('.tsx')) &&
+        !filePath.includes('workspace/') &&
+        !filePath.includes('apps/') &&
+        !filePath.includes('.claude/')) {
+      console.log(JSON.stringify({
+        decision: "allow",
+        message: `💡 CODE CHANGE: Consider running tests after editing.\n\nTask(subagent_type="agent-tanya-test-runner", prompt='{"task":"run_tests"}')`,
+      }));
+      return;
+    }
+  }
+
+  // SUGGEST: Lars for debugging when errors mentioned in prompt
+  if (tool_name === 'Task') {
+    // ReDoS protection: limit prompt size before regex matching
+    let prompt = (tool_input?.prompt || '').toLowerCase();
+    if (prompt.length > 10000) prompt = prompt.substring(0, 10000);
+    const agentType = tool_input?.subagent_type || '';
+
+    // If spawning general-purpose or explore for debugging, suggest lars
+    if ((agentType.includes('general') || agentType.includes('explore')) &&
+        (prompt.includes('bug') || prompt.includes('debug') || prompt.includes('error') ||
+         prompt.includes('not working') || prompt.includes('broken') || prompt.includes('why'))) {
+      suggest(`💡 FOR CODE ISSUES: Consider agent-lars-code-inspector.\n\nLars uses LSP to find:\n- Dead code and unused variables\n- Unused imports\n- Type errors\n\nTask(subagent_type="agent-lars-code-inspector", prompt='{"task":"inspect","file":"path/to/file.ts"}')`, 'agent-lars-code-inspector');
+      return;
+    }
+  }
+
+  // Allow the tool call
+  console.log(JSON.stringify({ decision: "allow" }));
+  process.exit(0);
+}