@automagik/genie 0.260201.2240

package/src/lib/hooks/presets/audited.ts

@@ -0,0 +1,191 @@
+/**
+ * Audited Hook Preset
+ *
+ * Logs all tool executions to a file for later review.
+ * Uses PostToolUse hooks to capture tool inputs and outputs.
+ *
+ * Usage:
+ *   const hooks = auditedHooks({ logPath: '~/.genie/audit.log' });
+ */
+
+import { appendFileSync, mkdirSync, existsSync } from 'fs';
+import { dirname, resolve } from 'path';
+import { homedir } from 'os';
+import type { AuditedConfig } from '../../../types/genie-config.js';
+import type { HookConfig, HookInput, HookOutput } from './collaborative.js';
+
+export interface AuditedHookConfig {
+  logPath: string;
+}
+
+/**
+ * Default configuration for audited hooks
+ */
+export const DEFAULT_AUDITED_CONFIG: AuditedHookConfig = {
+  logPath: '~/.genie/audit.log',
+};
+
+/**
+ * Expand ~ to home directory
+ */
+function expandTilde(path: string): string {
+  if (path.startsWith('~/')) {
+    return homedir() + path.slice(1);
+  }
+  if (path === '~') {
+    return homedir();
+  }
+  return path;
+}
+
+/**
+ * Format a tool input/output for logging
+ * Truncates very long values to avoid log bloat
+ */
+function formatForLog(value: unknown, maxLength: number = 1000): string {
+  try {
+    const str = JSON.stringify(value);
+    if (str.length > maxLength) {
+      return str.slice(0, maxLength) + '...[truncated]';
+    }
+    return str;
+  } catch {
+    return String(value);
+  }
+}
+
+/**
+ * Audit log entry
+ */
+interface AuditEntry {
+  timestamp: string;
+  tool: string;
+  input: unknown;
+  response?: unknown;
+  duration_ms?: number;
+}
+
+/**
+ * Append an entry to the audit log
+ */
+function appendToLog(logPath: string, entry: AuditEntry): void {
+  const expandedPath = resolve(expandTilde(logPath));
+  const dir = dirname(expandedPath);
+
+  // Ensure directory exists
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  const logLine = JSON.stringify({
+    ...entry,
+    input: formatForLog(entry.input),
+    response: entry.response ? formatForLog(entry.response) : undefined,
+  }) + '\n';
+
+  appendFileSync(expandedPath, logLine, 'utf-8');
+}
+
+// Track tool start times for duration calculation
+const toolStartTimes = new Map<string, number>();
+
+/**
+ * Create audited hooks configuration
+ *
+ * This hook captures all tool executions using PostToolUse hooks and
+ * logs them to a file in JSONL format for later review.
+ */
+export function auditedHooks(config: Partial<AuditedConfig> = {}): HookConfig {
+  const logPath = config.logPath || DEFAULT_AUDITED_CONFIG.logPath;
+
+  return {
+    PreToolUse: [
+      {
+        // Match all tools
+        matcher: /.*/,
+        timeout: 10,
+        hooks: [
+          async (input: HookInput, toolUseID, _options): Promise<HookOutput> => {
+            // Record start time for duration calculation
+            if (toolUseID) {
+              toolStartTimes.set(toolUseID, Date.now());
+            }
+            return { continue: true };
+          },
+        ],
+      },
+    ],
+    PostToolUse: [
+      {
+        // Match all tools
+        matcher: /.*/,
+        timeout: 10,
+        hooks: [
+          async (input: HookInput, toolUseID, _options): Promise<HookOutput> => {
+            // Type guard - only process PostToolUse events
+            if (input.hook_event_name !== 'PostToolUse') {
+              return { continue: true };
+            }
+
+            // Calculate duration if we have a start time
+            let duration_ms: number | undefined;
+            if (toolUseID && toolStartTimes.has(toolUseID)) {
+              duration_ms = Date.now() - toolStartTimes.get(toolUseID)!;
+              toolStartTimes.delete(toolUseID);
+            }
+
+            const entry: AuditEntry = {
+              timestamp: new Date().toISOString(),
+              tool: input.tool_name || 'unknown',
+              input: input.tool_input,
+              response: input.tool_response,
+              duration_ms,
+            };
+
+            try {
+              appendToLog(logPath, entry);
+            } catch (error) {
+              // Don't fail the tool call if logging fails
+              console.warn(`Audit log warning: ${error}`);
+            }
+
+            return { continue: true };
+          },
+        ],
+      },
+    ],
+  };
+}
+
+/**
+ * Read the audit log as an array of entries
+ * Useful for analysis and review
+ */
+export function readAuditLog(logPath: string = DEFAULT_AUDITED_CONFIG.logPath): AuditEntry[] {
+  const expandedPath = resolve(expandTilde(logPath));
+
+  if (!existsSync(expandedPath)) {
+    return [];
+  }
+
+  const { readFileSync } = require('fs');
+  const content = readFileSync(expandedPath, 'utf-8');
+  const lines = content.trim().split('\n').filter(Boolean);
+
+  return lines.map((line: string) => {
+    try {
+      return JSON.parse(line);
+    } catch {
+      return { error: 'parse_failed', raw: line };
+    }
+  });
+}
+
+/**
+ * Clear the audit log
+ */
+export function clearAuditLog(logPath: string = DEFAULT_AUDITED_CONFIG.logPath): void {
+  const expandedPath = resolve(expandTilde(logPath));
+  const { writeFileSync } = require('fs');
+  writeFileSync(expandedPath, '', 'utf-8');
+}

package/src/lib/hooks/presets/collaborative.ts

@@ -0,0 +1,143 @@
+/**
+ * Collaborative Hook Preset
+ *
+ * Makes all terminal operations human-observable via tmux.
+ * Intercepts Bash tool calls and rewrites them to go through `term exec`.
+ *
+ * Usage:
+ *   const hooks = collaborativeHooks({ sessionName: 'genie', windowName: 'shell' });
+ */
+
+import type { CollaborativeConfig } from '../../../types/genie-config.js';
+import { escapeForSingleQuotes } from '../utils/escape.js';
+
+export interface CollaborativeHookConfig {
+  sessionName: string;
+  windowName: string;
+}
+
+/**
+ * Default configuration for collaborative hooks
+ */
+export const DEFAULT_COLLABORATIVE_CONFIG: CollaborativeHookConfig = {
+  sessionName: 'genie',
+  windowName: 'shell',
+};
+
+/**
+ * Create collaborative hooks configuration
+ *
+ * This hook intercepts all Bash tool calls and rewrites them to execute
+ * through `term exec <session>:<window> '<command>'`, making all terminal
+ * operations visible in a tmux session that humans can attach to.
+ */
+export function collaborativeHooks(config: Partial<CollaborativeConfig> = {}): HookConfig {
+  const sessionName = config.sessionName || DEFAULT_COLLABORATIVE_CONFIG.sessionName;
+  const windowName = config.windowName || DEFAULT_COLLABORATIVE_CONFIG.windowName;
+  const target = `${sessionName}:${windowName}`;
+
+  return {
+    PreToolUse: [
+      {
+        matcher: 'Bash',
+        timeout: 30,
+        hooks: [
+          async (input, _toolUseID, _options) => {
+            // Type guard - only process PreToolUse events
+            if (input.hook_event_name !== 'PreToolUse') {
+              return { continue: true };
+            }
+
+            // Only intercept Bash tool
+            if (input.tool_name !== 'Bash') {
+              return { continue: true };
+            }
+
+            const bashInput = input.tool_input as {
+              command: string;
+              timeout?: number;
+              description?: string;
+              run_in_background?: boolean;
+            };
+
+            // Rewrite the command to go through term exec
+            const termCommand = `term exec ${target} '${escapeForSingleQuotes(bashInput.command)}'`;
+
+            // Create a brief description for the proxied command
+            const originalDesc = bashInput.description || bashInput.command.slice(0, 50);
+            const proxyDescription = `[term] ${originalDesc}${bashInput.command.length > 50 ? '...' : ''}`;
+
+            return {
+              continue: true,
+              hookSpecificOutput: {
+                hookEventName: 'PreToolUse',
+                updatedInput: {
+                  command: termCommand,
+                  timeout: bashInput.timeout,
+                  description: proxyDescription,
+                  run_in_background: bashInput.run_in_background,
+                },
+                permissionDecision: 'allow',
+                additionalContext: `Human can observe: tmux attach -t ${sessionName}`,
+              },
+            };
+          },
+        ],
+      },
+    ],
+  };
+}
+
+/**
+ * HookConfig type matching the Claude Agent SDK hook configuration
+ */
+export interface HookConfig {
+  PreToolUse?: Array<{
+    matcher: string | RegExp;
+    timeout?: number;
+    hooks: Array<HookCallback>;
+  }>;
+  PostToolUse?: Array<{
+    matcher?: string | RegExp;
+    timeout?: number;
+    hooks: Array<HookCallback>;
+  }>;
+  PermissionRequest?: Array<{
+    timeout?: number;
+    hooks: Array<HookCallback>;
+  }>;
+}
+
+/**
+ * Hook input types
+ */
+export interface HookInput {
+  hook_event_name: string;
+  tool_name?: string;
+  tool_input?: unknown;
+  tool_response?: unknown;
+}
+
+/**
+ * Hook callback type
+ */
+export type HookCallback = (
+  input: HookInput,
+  toolUseID: string | undefined,
+  options: { signal: AbortSignal }
+) => Promise<HookOutput>;
+
+/**
+ * Hook output type
+ */
+export interface HookOutput {
+  continue: boolean;
+  hookSpecificOutput?: {
+    hookEventName: string;
+    updatedInput?: unknown;
+    permissionDecision?: 'allow' | 'deny' | 'ask';
+    permissionDecisionReason?: string;
+    additionalContext?: string;
+    decision?: { behavior: 'allow' | 'deny' | 'ask' };
+  };
+}

package/src/lib/hooks/presets/sandboxed.ts

@@ -0,0 +1,153 @@
+/**
+ * Sandboxed Hook Preset
+ *
+ * Restricts file operations to specific directories.
+ * Intercepts PreToolUse events for file-related tools and denies operations
+ * outside the allowed paths.
+ *
+ * Usage:
+ *   const hooks = sandboxedHooks({ allowedPaths: ['~/projects', '/tmp'] });
+ */
+
+import { resolve, normalize } from 'path';
+import { homedir } from 'os';
+import type { SandboxedConfig } from '../../../types/genie-config.js';
+import type { HookConfig, HookInput, HookOutput } from './collaborative.js';
+
+export interface SandboxedHookConfig {
+  allowedPaths: string[];
+}
+
+/**
+ * Default configuration for sandboxed hooks
+ */
+export const DEFAULT_SANDBOXED_CONFIG: SandboxedHookConfig = {
+  allowedPaths: ['~/projects', '/tmp'],
+};
+
+/**
+ * Tools that access files
+ */
+const FILE_TOOLS = ['Read', 'Write', 'Edit', 'Glob', 'Grep'];
+
+/**
+ * Expand ~ to home directory
+ */
+function expandTilde(path: string): string {
+  if (path.startsWith('~/')) {
+    return homedir() + path.slice(1);
+  }
+  if (path === '~') {
+    return homedir();
+  }
+  return path;
+}
+
+/**
+ * Normalize and resolve a path, expanding ~
+ */
+function normalizePath(path: string): string {
+  return normalize(resolve(expandTilde(path)));
+}
+
+/**
+ * Check if a path is within any of the allowed paths
+ */
+function isWithinAllowed(targetPath: string, allowedPaths: string[]): boolean {
+  const normalizedTarget = normalizePath(targetPath);
+
+  for (const allowed of allowedPaths) {
+    const normalizedAllowed = normalizePath(allowed);
+
+    // Check if target is within or equal to allowed path
+    if (
+      normalizedTarget === normalizedAllowed ||
+      normalizedTarget.startsWith(normalizedAllowed + '/')
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Extract the path from tool input
+ */
+function extractPath(toolName: string, toolInput: unknown): string | null {
+  const input = toolInput as Record<string, unknown>;
+
+  switch (toolName) {
+    case 'Read':
+    case 'Write':
+    case 'Edit':
+      return (input.file_path as string) || null;
+    case 'Glob':
+      return (input.path as string) || process.cwd();
+    case 'Grep':
+      return (input.path as string) || process.cwd();
+    default:
+      return null;
+  }
+}
+
+/**
+ * Create sandboxed hooks configuration
+ *
+ * This hook intercepts PreToolUse events for file-related tools and
+ * denies operations on paths outside the allowed directories.
+ */
+export function sandboxedHooks(config: Partial<SandboxedConfig> = {}): HookConfig {
+  const allowedPaths = config.allowedPaths || DEFAULT_SANDBOXED_CONFIG.allowedPaths;
+
+  // Create a regex pattern that matches all file tools
+  const fileToolPattern = new RegExp(`^(${FILE_TOOLS.join('|')})$`);
+
+  return {
+    PreToolUse: [
+      {
+        matcher: fileToolPattern,
+        timeout: 30,
+        hooks: [
+          async (input: HookInput, _toolUseID, _options): Promise<HookOutput> => {
+            // Type guard - only process PreToolUse events
+            if (input.hook_event_name !== 'PreToolUse') {
+              return { continue: true };
+            }
+
+            const toolName = input.tool_name;
+            if (!toolName || !FILE_TOOLS.includes(toolName)) {
+              return { continue: true };
+            }
+
+            const targetPath = extractPath(toolName, input.tool_input);
+
+            // If we can't extract a path, allow the operation
+            // (better to be permissive than block valid operations)
+            if (!targetPath) {
+              return { continue: true };
+            }
+
+            // Check if path is within allowed directories
+            if (!isWithinAllowed(targetPath, allowedPaths)) {
+              const allowedDisplay = allowedPaths.map((p) =>
+                p.startsWith('~') ? p : expandTilde(p)
+              ).join(', ');
+
+              return {
+                continue: false,
+                hookSpecificOutput: {
+                  hookEventName: 'PreToolUse',
+                  permissionDecision: 'deny',
+                  permissionDecisionReason: `Path "${targetPath}" is outside the sandbox. Allowed paths: ${allowedDisplay}`,
+                },
+              };
+            }
+
+            return { continue: true };
+          },
+        ],
+      },
+    ],
+  };
+}

package/src/lib/hooks/presets/supervised.ts

@@ -0,0 +1,66 @@
+/**
+ * Supervised Hook Preset
+ *
+ * Requires explicit approval for file modifications.
+ * Intercepts PermissionRequest events and forces 'ask' behavior for Write/Edit tools.
+ *
+ * Usage:
+ *   const hooks = supervisedHooks({ alwaysAsk: ['Write', 'Edit'] });
+ */
+
+import type { SupervisedConfig } from '../../../types/genie-config.js';
+import type { HookConfig, HookInput, HookOutput } from './collaborative.js';
+
+export interface SupervisedHookConfig {
+  alwaysAsk: string[];
+}
+
+/**
+ * Default configuration for supervised hooks
+ */
+export const DEFAULT_SUPERVISED_CONFIG: SupervisedHookConfig = {
+  alwaysAsk: ['Write', 'Edit'],
+};
+
+/**
+ * Create supervised hooks configuration
+ *
+ * This hook intercepts PermissionRequest events and ensures that
+ * specified tools (default: Write, Edit) always require user approval.
+ */
+export function supervisedHooks(config: Partial<SupervisedConfig> = {}): HookConfig {
+  const alwaysAsk = config.alwaysAsk || DEFAULT_SUPERVISED_CONFIG.alwaysAsk;
+  const alwaysAskSet = new Set(alwaysAsk);
+
+  return {
+    PermissionRequest: [
+      {
+        timeout: 30,
+        hooks: [
+          async (input: HookInput, _toolUseID, _options): Promise<HookOutput> => {
+            // Type guard - only process PermissionRequest events
+            if (input.hook_event_name !== 'PermissionRequest') {
+              return { continue: true };
+            }
+
+            const toolName = input.tool_name;
+
+            // Check if this tool requires approval
+            if (toolName && alwaysAskSet.has(toolName)) {
+              return {
+                continue: true,
+                hookSpecificOutput: {
+                  hookEventName: 'PermissionRequest',
+                  decision: { behavior: 'ask' },
+                },
+              };
+            }
+
+            // Allow other tools to proceed normally
+            return { continue: true };
+          },
+        ],
+      },
+    ],
+  };
+}

package/src/lib/hooks/utils/escape.ts

@@ -0,0 +1,46 @@
+/**
+ * Shell escaping utilities for safely embedding commands in shell strings.
+ */
+
+/**
+ * Escape a string for safe embedding in single-quoted shell strings.
+ * e.g., "it's" becomes "it'\''s"
+ *
+ * This works by:
+ * 1. Ending the current single-quoted string: '
+ * 2. Adding an escaped single quote: \'
+ * 3. Starting a new single-quoted string: '
+ *
+ * So "it's cool" becomes 'it'\''s cool'
+ */
+export function escapeForSingleQuotes(str: string): string {
+  return str.replace(/'/g, "'\\''");
+}
+
+/**
+ * Escape a string for safe embedding in double-quoted shell strings.
+ * Escapes: $ ` " \ and newlines
+ */
+export function escapeForDoubleQuotes(str: string): string {
+  return str
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\$/g, '\\$')
+    .replace(/`/g, '\\`')
+    .replace(/\n/g, '\\n');
+}
+
+/**
+ * Wrap a command in single quotes with proper escaping.
+ * This is the safest way to pass arbitrary commands to shell.
+ */
+export function singleQuote(cmd: string): string {
+  return `'${escapeForSingleQuotes(cmd)}'`;
+}
+
+/**
+ * Wrap a command in double quotes with proper escaping.
+ */
+export function doubleQuote(cmd: string): string {
+  return `"${escapeForDoubleQuotes(cmd)}"`;
+}