@ebowwa/coder 0.2.1 → 0.7.64

package/packages/src/ecosystem/hooks/index.ts

@@ -0,0 +1,341 @@
+/**
+ * Hook System - Lifecycle event handlers
+ */
+
+import type { HookEvent, HookDefinition, HookInput, HookOutput } from "../../types/index.js";
+import { spawn } from "child_process";
+
+export type HookHandler = (input: HookInput) => Promise<HookOutput>;
+
+/**
+ * Prompt evaluator function type - calls LLM to evaluate hook prompt
+ */
+export type PromptEvaluator = (prompt: string, context: HookInput) => Promise<HookOutput>;
+
+/**
+ * Extended hook definition that supports shell commands, in-process handlers, and LLM prompts
+ */
+export interface ExtendedHookDefinition extends HookDefinition {
+  /** In-process handler function (alternative to command) */
+  handler?: HookHandler;
+  /** Prompt template for LLM-based evaluation (alternative to command) */
+  prompt?: string;
+  /** Matcher pattern for filtering which tools this hook applies to */
+  _matcher?: string;
+}
+
+export class HookManager {
+  private hooks = new Map<HookEvent, ExtendedHookDefinition[]>();
+  private timeout: number;
+  private promptEvaluator?: PromptEvaluator;
+
+  constructor(timeout = 60000, promptEvaluator?: PromptEvaluator) {
+    this.timeout = timeout;
+    this.promptEvaluator = promptEvaluator;
+  }
+
+  /**
+   * Set the prompt evaluator for LLM-based hooks
+   */
+  setPromptEvaluator(evaluator: PromptEvaluator): void {
+    this.promptEvaluator = evaluator;
+  }
+
+  register(event: HookEvent, definition: HookDefinition | ExtendedHookDefinition): void {
+    if (!this.hooks.has(event)) {
+      this.hooks.set(event, []);
+    }
+    this.hooks.get(event)?.push(definition as ExtendedHookDefinition);
+  }
+
+  /**
+   * Register an in-process handler for an event
+   */
+  registerHandler(event: HookEvent, handler: HookHandler, options?: { timeout?: number; enabled?: boolean }): void {
+    this.register(event, {
+      event,
+      command: "", // Not used for in-process handlers
+      handler,
+      timeout: options?.timeout,
+      enabled: options?.enabled ?? true,
+    });
+  }
+
+  registerAll(hooks: Record<HookEvent, HookDefinition[]>): void {
+    for (const [event, definitions] of Object.entries(hooks)) {
+      for (const def of definitions) {
+        this.register(event as HookEvent, def);
+      }
+    }
+  }
+
+  async execute(event: HookEvent, input: Omit<HookInput, "event" | "timestamp">): Promise<HookOutput> {
+    const definitions = this.hooks.get(event);
+    if (!definitions || definitions.length === 0) {
+      return { decision: "allow" };
+    }
+
+    const fullInput: HookInput = {
+      ...input,
+      event,
+      timestamp: Date.now(),
+    };
+
+    for (const def of definitions) {
+      if (def.enabled === false) continue;
+
+      // Check matcher if present
+      if (def._matcher && input.tool_name) {
+        try {
+          const regex = new RegExp(def._matcher);
+          if (!regex.test(input.tool_name)) {
+            // Matcher doesn't match, skip this hook
+            continue;
+          }
+        } catch {
+          // Invalid regex, skip
+          continue;
+        }
+      }
+
+      const result = await this.executeHook(def, fullInput);
+
+      if (result.decision === "deny" || result.decision === "block") {
+        return result;
+      }
+
+      // Apply modified input if provided
+      if (result.modified_input) {
+        Object.assign(input, result.modified_input);
+      }
+    }
+
+    return { decision: "allow" };
+  }
+
+  private async executeHook(def: ExtendedHookDefinition, input: HookInput): Promise<HookOutput> {
+    // If handler function is provided, use it directly
+    if (def.handler) {
+      try {
+        return await def.handler(input);
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+          decision: "deny",
+          reason: `Hook handler error: ${errorMessage}`,
+          errors: [errorMessage],
+        };
+      }
+    }
+
+    // If prompt is provided, use LLM evaluation
+    if (def.prompt && this.promptEvaluator) {
+      try {
+        return await this.promptEvaluator(def.prompt, input);
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+          decision: "deny",
+          reason: `Prompt hook error: ${errorMessage}`,
+          errors: [errorMessage],
+        };
+      }
+    }
+
+    // Skip hooks with empty commands (e.g., prompt-type hooks without evaluator)
+    if (!def.command || def.command.trim() === "") {
+      // Allow the operation to proceed if there's no command to execute
+      return { decision: "allow" };
+    }
+
+    // Shell command execution
+    const timeout = def.timeout || this.timeout;
+
+    try {
+      const result = await new Promise<HookOutput>((resolve, reject) => {
+        const proc = spawn(def.command, [], {
+          shell: true,
+          stdio: ["pipe", "pipe", "pipe"],
+        });
+
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+
+        const timer = setTimeout(() => {
+          timedOut = true;
+          proc.kill();
+          resolve({
+            decision: "deny",
+            reason: "Hook timeout",
+            errors: ["Hook execution timed out"],
+          });
+        }, timeout);
+
+        proc.stdout?.on("data", (data: Buffer) => {
+          stdout += data.toString();
+        });
+
+        proc.stderr?.on("data", (data: Buffer) => {
+          stderr += data.toString();
+        });
+
+        proc.on("close", (code: number | null) => {
+          clearTimeout(timer);
+          if (timedOut) return; // Already resolved
+
+          // Try to parse JSON from stdout first (works for all exit codes)
+          let parsedOutput: HookOutput | null = null;
+          if (stdout.trim()) {
+            try {
+              parsedOutput = JSON.parse(stdout) as HookOutput;
+            } catch {
+              // stdout not valid JSON, ignore
+            }
+          }
+
+          if (code === 0) {
+            // Success - use parsed output or default to allow
+            resolve(parsedOutput || { decision: "allow" });
+          } else if (code === 1) {
+            // Deny - use parsed output or fall back to stderr
+            if (parsedOutput) {
+              resolve(parsedOutput);
+            } else {
+              resolve({
+                decision: "deny",
+                reason: stderr || "Hook denied execution",
+                errors: stderr ? [stderr] : ["Hook denied execution"],
+              });
+            }
+          } else if (code === 2) {
+            // Block - use parsed output or fall back to stderr
+            if (parsedOutput) {
+              resolve(parsedOutput);
+            } else {
+              resolve({
+                decision: "block",
+                reason: stderr || "Hook blocked execution",
+                errors: stderr ? [stderr] : ["Hook blocked execution"],
+              });
+            }
+          } else {
+            // Other error - default to deny
+            resolve({
+              decision: "deny",
+              reason: `Hook exited with code ${code}`,
+              errors: [`Hook exited with code ${code}`],
+            });
+          }
+        });
+
+        proc.on("error", (error: Error) => {
+          clearTimeout(timer);
+          resolve({
+            decision: "deny",
+            reason: `Hook error: ${error.message}`,
+            errors: [error.message],
+          });
+        });
+
+        // Send input via stdin
+        proc.stdin?.write(JSON.stringify(input));
+        proc.stdin?.end();
+      });
+
+      return result;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      return {
+        decision: "deny",
+        reason: `Hook execution failed: ${errorMessage}`,
+        errors: [errorMessage],
+      };
+    }
+  }
+
+  getHooks(event: HookEvent): ExtendedHookDefinition[] {
+    return this.hooks.get(event) || [];
+  }
+
+  clear(event?: HookEvent): void {
+    if (event) {
+      this.hooks.delete(event);
+    } else {
+      this.hooks.clear();
+    }
+  }
+}
+
+// ============================================
+// BUILT-IN HOOKS
+// ============================================
+
+export const builtInHooks: Record<string, HookDefinition> = {
+  /**
+   * Example: Validate file paths before write
+   */
+  validateWrite: {
+    event: "PreToolUse",
+    command: `node -e '
+      const input = JSON.parse(require("fs").readFileSync(0, "utf8"));
+      if (input.tool_name === "Write") {
+        const path = input.tool_input.file_path;
+        if (path.includes("..") || path.startsWith("/etc/")) {
+          console.log(JSON.stringify({ decision: "deny", reason: "Unsafe path" }));
+          process.exit(1);
+        }
+      }
+      console.log(JSON.stringify({ decision: "allow" }));
+    '`,
+    timeout: 5000,
+    enabled: false,
+  },
+
+  /**
+   * Example: Log all tool uses
+   */
+  logToolUse: {
+    event: "PostToolUse",
+    command: `node -e '
+      const input = JSON.parse(require("fs").readFileSync(0, "utf8"));
+      console.error(\`[LOG] Tool: \${input.tool_name}\`);
+      console.log(JSON.stringify({ decision: "allow" }));
+    '`,
+    timeout: 5000,
+    enabled: false,
+  },
+};
+
+// ============================================
+// HOOK EVENT DOCUMENTATION
+// ============================================
+
+export const hookEventDocs: Record<HookEvent, string> = {
+  PreToolUse: "Before a tool is executed. Can modify input or deny execution.",
+  PostToolUse: "After a tool successfully executes. Can process result.",
+  PostToolUseFailure: "After a tool fails. Can handle error or retry.",
+  Stop: "When the agent stops (end_turn, max_tokens, error).",
+  UserPromptSubmit: "When user submits a prompt. Can modify or reject.",
+  SessionStart: "When a new session starts.",
+  SessionEnd: "When a session ends.",
+  Notification: "When a notification is sent.",
+  ConfigChange: "When configuration changes.",
+  WorktreeCreate: "When a git worktree is created.",
+};
+
+/**
+ * Exit codes for hook commands:
+ * 0 = Success, allow execution
+ * 1 = Show stderr, deny execution
+ * 2 = Block execution silently
+ */
+export const hookExitCodes = {
+  ALLOW: 0,
+  DENY: 1,
+  BLOCK: 2,
+};
+
+// Re-export prompt evaluator utilities
+export { createPromptEvaluator, createMockPromptEvaluator } from "./prompt-evaluator.js";
+export type { PromptEvaluatorOptions } from "./prompt-evaluator.js";

package/packages/src/ecosystem/hooks/prompt-evaluator.ts

@@ -0,0 +1,300 @@
+/**
+ * Prompt Evaluator - LLM-based hook evaluation
+ *
+ * Evaluates hook prompts by calling the Claude API to make decisions
+ * about tool execution based on natural language rules.
+ */
+
+import type { HookInput, HookOutput } from "../../types/index.js";
+import type { PromptEvaluator } from "./index.js";
+
+/**
+ * Options for creating a prompt evaluator
+ */
+export interface PromptEvaluatorOptions {
+  /** Anthropic API key */
+  apiKey: string;
+  /** Model to use for evaluation (default: claude-haiku-4-5 for speed) */
+  model?: string;
+  /** Max tokens for response (default: 256) */
+  maxTokens?: number;
+  /** System prompt for the evaluator */
+  systemPrompt?: string;
+  /** Base URL for API (default: from ANTHROPIC_BASE_URL env or https://api.anthropic.com) */
+  baseUrl?: string;
+}
+
+/**
+ * Default system prompt for hook evaluation
+ */
+const DEFAULT_SYSTEM_PROMPT = `You are a hook evaluator for Coder. Your job is to evaluate tool usage against security and best-practice rules.
+
+You MUST respond with ONLY a valid JSON object in this exact format:
+{
+  "decision": "allow" | "deny" | "block",
+  "reason": "Optional explanation for the decision",
+  "modified_input": { ... } // Optional: modified tool input if you want to change it
+}
+
+Rules:
+- "allow": Let the tool execute normally
+- "deny": Prevent execution and show the user the reason
+- "block": Prevent execution silently (no message shown)
+- Only modify input if absolutely necessary and you're certain of the correct format
+
+Be concise and make quick decisions. Do not explain your reasoning in prose - only use the JSON format.`;
+
+/**
+ * Interpolate variables in a prompt template
+ */
+function interpolatePrompt(template: string, input: HookInput): string {
+  let result = template;
+
+  // Replace $ARGUMENTS with tool input as JSON
+  if (input.tool_input) {
+    result = result.replace(/\$ARGUMENTS/g, JSON.stringify(input.tool_input, null, 2));
+  }
+
+  // Replace $TOOL_NAME with tool name
+  if (input.tool_name) {
+    result = result.replace(/\$TOOL_NAME/g, input.tool_name);
+  }
+
+  // Replace $EVENT with event name
+  result = result.replace(/\$EVENT/g, input.event);
+
+  // Replace $SESSION_ID with session ID
+  if (input.session_id) {
+    result = result.replace(/\$SESSION_ID/g, input.session_id);
+  }
+
+  // Replace $TIMESTAMP with timestamp
+  result = result.replace(/\$TIMESTAMP/g, String(input.timestamp));
+
+  // Replace $ERROR with error message if present
+  if (input.error) {
+    result = result.replace(/\$ERROR/g, input.error);
+  }
+
+  // Replace $TOOL_RESULT with tool result if present
+  if (input.tool_result) {
+    const resultStr = typeof input.tool_result.content === "string"
+      ? input.tool_result.content
+      : JSON.stringify(input.tool_result.content);
+    result = result.replace(/\$TOOL_RESULT/g, resultStr);
+  }
+
+  return result;
+}
+
+/**
+ * Parse the LLM response into a HookOutput
+ * Supports multiple JSON formats:
+ * 1. Standard: { "decision": "allow" | "deny" | "block", "reason": "..." }
+ * 2. Standard format: { "continue": true/false, "hookSpecificOutput": {...} }
+ */
+function parseHookOutput(responseText: string): HookOutput {
+  // Try to extract JSON from the response
+  // The model might wrap it in markdown code blocks or add extra text
+
+  let parsed: Record<string, unknown> | null = null;
+
+  // First, try direct parse
+  try {
+    parsed = JSON.parse(responseText) as Record<string, unknown>;
+  } catch {
+    // Not valid JSON directly
+  }
+
+  // Try to extract JSON from markdown code block
+  if (!parsed) {
+    const jsonBlockMatch = responseText.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
+    if (jsonBlockMatch?.[1]) {
+      try {
+        parsed = JSON.parse(jsonBlockMatch[1].trim()) as Record<string, unknown>;
+      } catch {
+        // Invalid JSON in code block
+      }
+    }
+  }
+
+  // Try to find JSON object anywhere in the response
+  if (!parsed) {
+    const jsonMatch = responseText.match(/\{[\s\S]*?\}/);
+    if (jsonMatch) {
+      try {
+        parsed = JSON.parse(jsonMatch[0]) as Record<string, unknown>;
+      } catch {
+        // Invalid JSON
+      }
+    }
+  }
+
+  if (!parsed) {
+    // If we can't parse JSON, default to allow with a warning
+    return {
+      decision: "allow",
+      reason: "Hook response could not be parsed as JSON, allowing by default",
+    };
+  }
+
+  // Format 1: Standard { decision: "allow" | "deny" | "block" }
+  if ("decision" in parsed) {
+    return {
+      decision: (parsed.decision as "allow" | "deny" | "block") || "allow",
+      reason: parsed.reason as string | undefined,
+      modified_input: parsed.modified_input as Record<string, unknown> | undefined,
+    };
+  }
+
+  // Format 2: Standard { continue: true/false, hookSpecificOutput: {...} }
+  if ("continue" in parsed) {
+    const shouldContinue = Boolean(parsed.continue);
+    if (shouldContinue) {
+      return { decision: "allow" };
+    }
+
+    // Extract reason from hookSpecificOutput if present
+    const hookOutput = parsed.hookSpecificOutput as Record<string, unknown> | undefined;
+    const reason = hookOutput?.permissionDecisionReason as string | undefined;
+
+    return {
+      decision: "deny",
+      reason: reason || "Hook denied execution",
+    };
+  }
+
+  // Unknown format, default to allow
+  return {
+    decision: "allow",
+    reason: "Unknown hook response format, allowing by default",
+  };
+}
+
+/**
+ * Make a non-streaming API call to Claude
+ */
+async function callClaudeAPI(
+  apiKey: string,
+  model: string,
+  maxTokens: number,
+  systemPrompt: string,
+  userPrompt: string,
+  baseUrl: string = "https://api.anthropic.com"
+): Promise<string> {
+  const response = await fetch(`${baseUrl}/v1/messages`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-api-key": apiKey,
+      "anthropic-version": "2023-06-01",
+    },
+    body: JSON.stringify({
+      model,
+      max_tokens: maxTokens,
+      system: systemPrompt,
+      messages: [
+        {
+          role: "user",
+          content: userPrompt,
+        },
+      ],
+    }),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`API error: ${response.status} - ${errorText}`);
+  }
+
+  const data = await response.json() as {
+    content: Array<{ type: string; text?: string }>;
+  };
+
+  // Extract text from response
+  const textContent = data.content
+    .filter((block) => block.type === "text")
+    .map((block) => block.text || "")
+    .join("");
+
+  return textContent;
+}
+
+/**
+ * Create a prompt evaluator that uses the Claude API
+ */
+export function createPromptEvaluator(options: PromptEvaluatorOptions): PromptEvaluator {
+  const {
+    apiKey,
+    model = "claude-haiku-4-5", // Use Haiku for fast evaluation
+    maxTokens = 256,
+    systemPrompt = DEFAULT_SYSTEM_PROMPT,
+    baseUrl = process.env.ANTHROPIC_BASE_URL || "https://api.anthropic.com",
+  } = options;
+
+  return async (promptTemplate: string, context: HookInput): Promise<HookOutput> => {
+    // Interpolate variables in the prompt
+    const userPrompt = interpolatePrompt(promptTemplate, context);
+
+    try {
+      // Call the API
+      const responseText = await callClaudeAPI(
+        apiKey,
+        model,
+        maxTokens,
+        systemPrompt,
+        userPrompt,
+        baseUrl
+      );
+
+      if (!responseText) {
+        return { decision: "allow" };
+      }
+
+      // Parse the response
+      return parseHookOutput(responseText);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      // On error, allow by default but log the issue
+      console.error(`[PromptEvaluator] Error evaluating hook: ${errorMessage}`);
+      return {
+        decision: "allow",
+        reason: `Hook evaluation failed: ${errorMessage}`,
+      };
+    }
+  };
+}
+
+/**
+ * Create a mock prompt evaluator for testing
+ * Returns canned responses based on patterns in the prompt
+ */
+export function createMockPromptEvaluator(): PromptEvaluator {
+  return async (promptTemplate: string, context: HookInput): Promise<HookOutput> => {
+    // Simple mock logic for testing
+    const prompt = promptTemplate.toLowerCase();
+    const toolInput = context.tool_input;
+
+    // If checking for MCP alternatives and we have a Bash command
+    if (prompt.includes("mcp") && toolInput && "command" in toolInput) {
+      const command = String(toolInput.command);
+
+      // Check for common patterns that have MCP alternatives
+      if (command.includes("git status")) {
+        return {
+          decision: "deny",
+          reason: "Consider using the Git MCP tool instead of running git commands directly",
+        };
+      }
+      if (command.includes("gh ")) {
+        return {
+          decision: "deny",
+          reason: "Consider using the GitHub MCP tool instead of gh CLI",
+        };
+      }
+    }
+
+    // Default allow
+    return { decision: "allow" };
+  };
+}