feat: add internal hooks system

2026-01-17 01:31:39 +00:00
parent a76cbc43bb
commit faba508fe0
39 changed files with 4241 additions and 28 deletions
--- a/src/hooks/bundled-dir.ts
+++ b/src/hooks/bundled-dir.ts
@@ -0,0 +1,40 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function resolveBundledHooksDir(): string | undefined {
+  const override = process.env.CLAWDBOT_BUNDLED_HOOKS_DIR?.trim();
+  if (override) return override;
+
+  // bun --compile: ship a sibling `hooks/bundled/` next to the executable.
+  try {
+    const execDir = path.dirname(process.execPath);
+    const sibling = path.join(execDir, "hooks", "bundled");
+    if (fs.existsSync(sibling)) return sibling;
+  } catch {
+    // ignore
+  }
+
+  // npm: resolve `<packageRoot>/dist/hooks/bundled` relative to this module (compiled hooks).
+  // This path works when installed via npm: node_modules/clawdbot/dist/hooks/bundled-dir.js
+  try {
+    const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+    const distBundled = path.join(moduleDir, "bundled");
+    if (fs.existsSync(distBundled)) return distBundled;
+  } catch {
+    // ignore
+  }
+
+  // dev: resolve `<packageRoot>/src/hooks/bundled` relative to dist/hooks/bundled-dir.js
+  // This path works in dev: dist/hooks/bundled-dir.js -> ../../src/hooks/bundled
+  try {
+    const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+    const root = path.resolve(moduleDir, "..", "..");
+    const srcBundled = path.join(root, "src", "hooks", "bundled");
+    if (fs.existsSync(srcBundled)) return srcBundled;
+  } catch {
+    // ignore
+  }
+
+  return undefined;
+}
--- a/src/hooks/bundled/README.md
+++ b/src/hooks/bundled/README.md
@@ -0,0 +1,186 @@
+# Bundled Internal Hooks
+
+This directory contains internal hooks that ship with Clawdbot. These hooks are automatically discovered and can be enabled/disabled via CLI or configuration.
+
+## Available Hooks
+
+### 💾 session-memory
+
+Automatically saves session context to memory when you issue `/new`.
+
+**Events**: `command:new`
+**What it does**: Creates a dated memory file with LLM-generated slug based on conversation content.
+**Output**: `<workspace>/memory/YYYY-MM-DD-slug.md` (defaults to `~/clawd`)
+
+**Enable**:
+```bash
+clawdbot hooks internal enable session-memory
+```
+
+### 📝 command-logger
+
+Logs all command events to a centralized audit file.
+
+**Events**: `command` (all commands)
+**What it does**: Appends JSONL entries to command log file.
+**Output**: `~/.clawdbot/logs/commands.log`
+
+**Enable**:
+```bash
+clawdbot hooks internal enable command-logger
+```
+
+## Hook Structure
+
+Each hook is a directory containing:
+
+- **HOOK.md**: Metadata and documentation in YAML frontmatter + Markdown
+- **handler.ts**: The hook handler function (default export)
+
+Example structure:
+```
+session-memory/
+├── HOOK.md          # Metadata + docs
+└── handler.ts       # Handler implementation
+```
+
+## HOOK.md Format
+
+```yaml
+---
+name: my-hook
+description: "Short description"
+homepage: https://docs.clawd.bot/hooks/my-hook
+metadata: {"clawdbot":{"emoji":"🔗","events":["command:new"],"requires":{"bins":["node"]}}}
+---
+
+# Hook Title
+
+Documentation goes here...
+```
+
+### Metadata Fields
+
+- **emoji**: Display emoji for CLI
+- **events**: Array of events to listen for (e.g., `["command:new", "session:start"]`)
+- **requires**: Optional requirements
+  - **bins**: Required binaries on PATH
+  - **anyBins**: At least one of these binaries must be present
+  - **env**: Required environment variables
+  - **config**: Required config paths (e.g., `["workspace.dir"]`)
+  - **os**: Required platforms (e.g., `["darwin", "linux"]`)
+- **install**: Installation methods (for bundled hooks: `[{"id":"bundled","kind":"bundled"}]`)
+
+## Creating Custom Hooks
+
+To create your own hooks, place them in:
+
+- **Workspace hooks**: `<workspace>/hooks/` (highest precedence)
+- **Managed hooks**: `~/.clawdbot/hooks/` (shared across workspaces)
+
+Custom hooks follow the same structure as bundled hooks.
+
+## Managing Hooks
+
+List all hooks:
+```bash
+clawdbot hooks internal list
+```
+
+Show hook details:
+```bash
+clawdbot hooks internal info session-memory
+```
+
+Check hook status:
+```bash
+clawdbot hooks internal check
+```
+
+Enable/disable:
+```bash
+clawdbot hooks internal enable session-memory
+clawdbot hooks internal disable command-logger
+```
+
+## Configuration
+
+Hooks can be configured in `~/.clawdbot/clawdbot.json`:
+
+```json
+{
+  "hooks": {
+    "internal": {
+      "enabled": true,
+      "entries": {
+        "session-memory": {
+          "enabled": true
+        },
+        "command-logger": {
+          "enabled": false
+        }
+      }
+    }
+  }
+}
+```
+
+## Event Types
+
+Currently supported events:
+
+- **command**: All command events
+- **command:new**: `/new` command specifically
+- **command:reset**: `/reset` command
+- **command:stop**: `/stop` command
+
+More event types coming soon (session lifecycle, agent errors, etc.).
+
+## Handler API
+
+Hook handlers receive an `InternalHookEvent` object:
+
+```typescript
+interface InternalHookEvent {
+  type: 'command' | 'session' | 'agent';
+  action: string;              // e.g., 'new', 'reset', 'stop'
+  sessionKey: string;
+  context: Record<string, unknown>;
+  timestamp: Date;
+  messages: string[];          // Push messages here to send to user
+}
+```
+
+Example handler:
+
+```typescript
+import type { InternalHookHandler } from '../../src/hooks/internal-hooks.js';
+
+const myHandler: InternalHookHandler = async (event) => {
+  if (event.type !== 'command' || event.action !== 'new') {
+    return;
+  }
+
+  // Your logic here
+  console.log('New command triggered!');
+
+  // Optionally send message to user
+  event.messages.push('✨ Hook executed!');
+};
+
+export default myHandler;
+```
+
+## Testing
+
+Test your hooks by:
+
+1. Place hook in workspace hooks directory
+2. Restart gateway: `pkill -9 -f 'clawdbot.*gateway' && pnpm clawdbot gateway`
+3. Enable the hook: `clawdbot hooks internal enable my-hook`
+4. Trigger the event (e.g., send `/new` command)
+5. Check gateway logs for hook execution
+
+## Documentation
+
+Full documentation: https://docs.clawd.bot/internal-hooks
--- a/src/hooks/bundled/command-logger/HOOK.md
+++ b/src/hooks/bundled/command-logger/HOOK.md
@@ -0,0 +1,109 @@
+---
+name: command-logger
+description: "Log all command events to a centralized audit file"
+homepage: https://docs.clawd.bot/internal-hooks#command-logger
+metadata: {"clawdbot":{"emoji":"📝","events":["command"],"install":[{"id":"bundled","kind":"bundled","label":"Bundled with Clawdbot"}]}}
+---
+
+# Command Logger Hook
+
+Logs all command events (`/new`, `/reset`, `/stop`, etc.) to a centralized audit log file for debugging and monitoring purposes.
+
+## What It Does
+
+Every time you issue a command to the agent:
+
+1. **Captures event details** - Command action, timestamp, session key, sender ID, source
+2. **Appends to log file** - Writes a JSON line to `~/.clawdbot/logs/commands.log`
+3. **Silent operation** - Runs in the background without user notifications
+
+## Output Format
+
+Log entries are written in JSONL (JSON Lines) format:
+
+```json
+{"timestamp":"2026-01-16T14:30:00.000Z","action":"new","sessionKey":"agent:main:main","senderId":"+1234567890","source":"telegram"}
+{"timestamp":"2026-01-16T15:45:22.000Z","action":"stop","sessionKey":"agent:main:main","senderId":"user@example.com","source":"whatsapp"}
+```
+
+## Use Cases
+
+- **Debugging**: Track when commands were issued and from which source
+- **Auditing**: Monitor command usage across different channels
+- **Analytics**: Analyze command patterns and frequency
+- **Troubleshooting**: Investigate issues by reviewing command history
+
+## Log File Location
+
+`~/.clawdbot/logs/commands.log`
+
+## Requirements
+
+No requirements - this hook works out of the box on all platforms.
+
+## Configuration
+
+No configuration needed. The hook automatically:
+- Creates the log directory if it doesn't exist
+- Appends to the log file (doesn't overwrite)
+- Handles errors silently without disrupting command execution
+
+## Disabling
+
+To disable this hook:
+
+```bash
+clawdbot hooks internal disable command-logger
+```
+
+Or via config:
+
+```json
+{
+  "hooks": {
+    "internal": {
+      "entries": {
+        "command-logger": { "enabled": false }
+      }
+    }
+  }
+}
+```
+
+## Log Rotation
+
+The hook does not automatically rotate logs. To manage log size, you can:
+
+1. **Manual rotation**:
+   ```bash
+   mv ~/.clawdbot/logs/commands.log ~/.clawdbot/logs/commands.log.old
+   ```
+
+2. **Use logrotate** (Linux):
+   Create `/etc/logrotate.d/clawdbot`:
+   ```
+   /home/username/.clawdbot/logs/commands.log {
+       weekly
+       rotate 4
+       compress
+       missingok
+       notifempty
+   }
+   ```
+
+## Viewing Logs
+
+View recent commands:
+```bash
+tail -n 20 ~/.clawdbot/logs/commands.log
+```
+
+Pretty-print with jq:
+```bash
+cat ~/.clawdbot/logs/commands.log | jq .
+```
+
+Filter by action:
+```bash
+grep '"action":"new"' ~/.clawdbot/logs/commands.log | jq .
+```
--- a/src/hooks/bundled/command-logger/handler.ts
+++ b/src/hooks/bundled/command-logger/handler.ts
@@ -0,0 +1,64 @@
+/**
+ * Example internal hook handler: Log all commands to a file
+ *
+ * This handler demonstrates how to create a hook that logs all command events
+ * to a centralized log file for audit/debugging purposes.
+ *
+ * To enable this handler, add it to your config:
+ *
+ * ```json
+ * {
+ *   "hooks": {
+ *     "internal": {
+ *       "enabled": true,
+ *       "handlers": [
+ *         {
+ *           "event": "command",
+ *           "module": "./hooks/handlers/command-logger.ts"
+ *         }
+ *       ]
+ *     }
+ *   }
+ * }
+ * ```
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import type { InternalHookHandler } from '../../internal-hooks.js';
+
+/**
+ * Log all command events to a file
+ */
+const logCommand: InternalHookHandler = async (event) => {
+  // Only trigger on command events
+  if (event.type !== 'command') {
+    return;
+  }
+
+  try {
+    // Create log directory
+    const logDir = path.join(os.homedir(), '.clawdbot', 'logs');
+    await fs.mkdir(logDir, { recursive: true });
+
+    // Append to command log file
+    const logFile = path.join(logDir, 'commands.log');
+    const logLine = JSON.stringify({
+      timestamp: event.timestamp.toISOString(),
+      action: event.action,
+      sessionKey: event.sessionKey,
+      senderId: event.context.senderId ?? 'unknown',
+      source: event.context.commandSource ?? 'unknown',
+    }) + '\n';
+
+    await fs.appendFile(logFile, logLine, 'utf-8');
+  } catch (err) {
+    console.error(
+      '[command-logger] Failed to log command:',
+      err instanceof Error ? err.message : String(err)
+    );
+  }
+};
+
+export default logCommand;
--- a/src/hooks/bundled/session-memory/HOOK.md
+++ b/src/hooks/bundled/session-memory/HOOK.md
@@ -0,0 +1,76 @@
+---
+name: session-memory
+description: "Save session context to memory when /new command is issued"
+homepage: https://docs.clawd.bot/internal-hooks#session-memory
+metadata: {"clawdbot":{"emoji":"💾","events":["command:new"],"requires":{"config":["workspace.dir"]},"install":[{"id":"bundled","kind":"bundled","label":"Bundled with Clawdbot"}]}}
+---
+
+# Session Memory Hook
+
+Automatically saves session context to your workspace memory when you issue the `/new` command.
+
+## What It Does
+
+When you run `/new` to start a fresh session:
+
+1. **Finds the previous session** - Uses the pre-reset session entry to locate the correct transcript
+2. **Extracts conversation** - Reads the last 15 lines of conversation from the session
+3. **Generates descriptive slug** - Uses LLM to create a meaningful filename slug based on conversation content
+4. **Saves to memory** - Creates a new file at `<workspace>/memory/YYYY-MM-DD-slug.md`
+5. **Sends confirmation** - Notifies you with the file path
+
+## Output Format
+
+Memory files are created with the following format:
+
+```markdown
+# Session: 2026-01-16 14:30:00 UTC
+
+- **Session Key**: agent:main:main
+- **Session ID**: abc123def456
+- **Source**: telegram
+```
+
+## Filename Examples
+
+The LLM generates descriptive slugs based on your conversation:
+
+- `2026-01-16-vendor-pitch.md` - Discussion about vendor evaluation
+- `2026-01-16-api-design.md` - API architecture planning
+- `2026-01-16-bug-fix.md` - Debugging session
+- `2026-01-16-1430.md` - Fallback timestamp if slug generation fails
+
+## Requirements
+
+- **Config**: `workspace.dir` must be set (automatically configured during onboarding)
+
+The hook uses your configured LLM provider to generate slugs, so it works with any provider (Anthropic, OpenAI, etc.).
+
+## Configuration
+
+No additional configuration required. The hook automatically:
+- Uses your workspace directory (`~/clawd` by default)
+- Uses your configured LLM for slug generation
+- Falls back to timestamp slugs if LLM is unavailable
+
+## Disabling
+
+To disable this hook:
+
+```bash
+clawdbot hooks internal disable session-memory
+```
+
+Or remove it from your config:
+
+```json
+{
+  "hooks": {
+    "internal": {
+      "entries": {
+        "session-memory": { "enabled": false }
+      }
+    }
+  }
+}
+```
--- a/src/hooks/bundled/session-memory/handler.ts
+++ b/src/hooks/bundled/session-memory/handler.ts
@@ -0,0 +1,174 @@
+/**
+ * Session memory hook handler
+ *
+ * Saves session context to memory when /new command is triggered
+ * Creates a new dated memory file with LLM-generated slug
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import type { ClawdbotConfig } from '../../../config/config.js';
+import { resolveAgentWorkspaceDir } from '../../../agents/agent-scope.js';
+import { resolveAgentIdFromSessionKey } from '../../../routing/session-key.js';
+import type { InternalHookHandler } from '../../internal-hooks.js';
+
+/**
+ * Read recent messages from session file for slug generation
+ */
+async function getRecentSessionContent(sessionFilePath: string): Promise<string | null> {
+  try {
+    const content = await fs.readFile(sessionFilePath, 'utf-8');
+    const lines = content.trim().split('\n');
+
+    // Get last 15 lines (recent conversation)
+    const recentLines = lines.slice(-15);
+
+    // Parse JSONL and extract messages
+    const messages: string[] = [];
+    for (const line of recentLines) {
+      try {
+        const entry = JSON.parse(line);
+        // Session files have entries with type="message" containing a nested message object
+        if (entry.type === 'message' && entry.message) {
+          const msg = entry.message;
+          const role = msg.role;
+          if ((role === 'user' || role === 'assistant') && msg.content) {
+            // Extract text content
+            const text = Array.isArray(msg.content)
+              ? msg.content.find((c: any) => c.type === 'text')?.text
+              : msg.content;
+            if (text && !text.startsWith('/')) {
+              messages.push(`${role}: ${text}`);
+            }
+          }
+        }
+      } catch {
+        // Skip invalid JSON lines
+      }
+    }
+
+    return messages.join('\n');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save session context to memory when /new command is triggered
+ */
+const saveSessionToMemory: InternalHookHandler = async (event) => {
+  // Only trigger on 'new' command
+  if (event.type !== 'command' || event.action !== 'new') {
+    return;
+  }
+
+  try {
+    console.log('[session-memory] Hook triggered for /new command');
+
+    const context = event.context || {};
+    const cfg = context.cfg as ClawdbotConfig | undefined;
+    const agentId = resolveAgentIdFromSessionKey(event.sessionKey);
+    const workspaceDir = cfg
+      ? resolveAgentWorkspaceDir(cfg, agentId)
+      : path.join(os.homedir(), 'clawd');
+    const memoryDir = path.join(workspaceDir, 'memory');
+    await fs.mkdir(memoryDir, { recursive: true });
+
+    // Get today's date for filename
+    const now = new Date(event.timestamp);
+    const dateStr = now.toISOString().split('T')[0]; // YYYY-MM-DD
+
+    // Generate descriptive slug from session using LLM
+    const sessionEntry = (
+      context.previousSessionEntry ||
+      context.sessionEntry ||
+      {}
+    ) as Record<string, unknown>;
+    const currentSessionId = sessionEntry.sessionId as string;
+    const currentSessionFile = sessionEntry.sessionFile as string;
+
+    console.log('[session-memory] Current sessionId:', currentSessionId);
+    console.log('[session-memory] Current sessionFile:', currentSessionFile);
+    console.log('[session-memory] cfg present:', !!cfg);
+
+    const sessionFile = currentSessionFile || undefined;
+
+    let slug: string | null = null;
+    let sessionContent: string | null = null;
+
+    if (sessionFile) {
+      // Get recent conversation content
+      sessionContent = await getRecentSessionContent(sessionFile);
+      console.log('[session-memory] sessionContent length:', sessionContent?.length || 0);
+
+      if (sessionContent && cfg) {
+        console.log('[session-memory] Calling generateSlugViaLLM...');
+        // Dynamically import the LLM slug generator (avoids module caching issues)
+        // When compiled, handler is at dist/hooks/bundled/session-memory/handler.js
+        // Going up ../.. puts us at dist/hooks/, so just add llm-slug-generator.js
+        const clawdbotRoot = path.resolve(path.dirname(import.meta.url.replace('file://', '')), '../..');
+        const slugGenPath = path.join(clawdbotRoot, 'llm-slug-generator.js');
+        const { generateSlugViaLLM } = await import(slugGenPath);
+
+        // Use LLM to generate a descriptive slug
+        slug = await generateSlugViaLLM({ sessionContent, cfg });
+        console.log('[session-memory] Generated slug:', slug);
+      }
+    }
+
+    // If no slug, use timestamp
+    if (!slug) {
+      const timeSlug = now.toISOString().split('T')[1]!.split('.')[0]!.replace(/:/g, '');
+      slug = timeSlug.slice(0, 4); // HHMM
+      console.log('[session-memory] Using fallback timestamp slug:', slug);
+    }
+
+    // Create filename with date and slug
+    const filename = `${dateStr}-${slug}.md`;
+    const memoryFilePath = path.join(memoryDir, filename);
+    console.log('[session-memory] Generated filename:', filename);
+    console.log('[session-memory] Full path:', memoryFilePath);
+
+    // Format time as HH:MM:SS UTC
+    const timeStr = now.toISOString().split('T')[1]!.split('.')[0];
+
+    // Extract context details
+    const sessionId = (sessionEntry.sessionId as string) || 'unknown';
+    const source = (context.commandSource as string) || 'unknown';
+
+    // Build Markdown entry
+    const entryParts = [
+      `# Session: ${dateStr} ${timeStr} UTC`,
+      '',
+      `- **Session Key**: ${event.sessionKey}`,
+      `- **Session ID**: ${sessionId}`,
+      `- **Source**: ${source}`,
+      '',
+    ];
+
+    // Include conversation content if available
+    if (sessionContent) {
+      entryParts.push('## Conversation Summary', '', sessionContent, '');
+    }
+
+    const entry = entryParts.join('\n');
+
+    // Write to new memory file
+    await fs.writeFile(memoryFilePath, entry, 'utf-8');
+    console.log('[session-memory] Memory file written successfully');
+
+    // Send confirmation message to user with filename
+    const relPath = memoryFilePath.replace(os.homedir(), '~');
+    const confirmMsg = `💾 Session context saved to memory before reset.\n📄 ${relPath}`;
+    event.messages.push(confirmMsg);
+    console.log('[session-memory] Confirmation message queued:', confirmMsg);
+  } catch (err) {
+    console.error(
+      '[session-memory] Failed to save session memory:',
+      err instanceof Error ? err.message : String(err)
+    );
+  }
+};
+
+export default saveSessionToMemory;
--- a/src/hooks/config.ts
+++ b/src/hooks/config.ts
@@ -0,0 +1,134 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { ClawdbotConfig, HookConfig } from "../config/config.js";
+import { resolveHookKey } from "./frontmatter.js";
+import type { HookEligibilityContext, HookEntry } from "./types.js";
+
+const DEFAULT_CONFIG_VALUES: Record<string, boolean> = {
+  "browser.enabled": true,
+  "workspace.dir": true,
+};
+
+function isTruthy(value: unknown): boolean {
+  if (value === undefined || value === null) return false;
+  if (typeof value === "boolean") return value;
+  if (typeof value === "number") return value !== 0;
+  if (typeof value === "string") return value.trim().length > 0;
+  return true;
+}
+
+export function resolveConfigPath(config: ClawdbotConfig | undefined, pathStr: string) {
+  const parts = pathStr.split(".").filter(Boolean);
+  let current: unknown = config;
+  for (const part of parts) {
+    if (typeof current !== "object" || current === null) return undefined;
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current;
+}
+
+export function isConfigPathTruthy(config: ClawdbotConfig | undefined, pathStr: string): boolean {
+  const value = resolveConfigPath(config, pathStr);
+  if (value === undefined && pathStr in DEFAULT_CONFIG_VALUES) {
+    return DEFAULT_CONFIG_VALUES[pathStr] === true;
+  }
+  return isTruthy(value);
+}
+
+export function resolveHookConfig(
+  config: ClawdbotConfig | undefined,
+  hookKey: string,
+): HookConfig | undefined {
+  const hooks = config?.hooks?.internal?.entries;
+  if (!hooks || typeof hooks !== "object") return undefined;
+  const entry = (hooks as Record<string, HookConfig | undefined>)[hookKey];
+  if (!entry || typeof entry !== "object") return undefined;
+  return entry;
+}
+
+export function resolveRuntimePlatform(): string {
+  return process.platform;
+}
+
+export function hasBinary(bin: string): boolean {
+  const pathEnv = process.env.PATH ?? "";
+  const parts = pathEnv.split(path.delimiter).filter(Boolean);
+  for (const part of parts) {
+    const candidate = path.join(part, bin);
+    try {
+      fs.accessSync(candidate, fs.constants.X_OK);
+      return true;
+    } catch {
+      // keep scanning
+    }
+  }
+  return false;
+}
+
+export function shouldIncludeHook(params: {
+  entry: HookEntry;
+  config?: ClawdbotConfig;
+  eligibility?: HookEligibilityContext;
+}): boolean {
+  const { entry, config, eligibility } = params;
+  const hookKey = resolveHookKey(entry.hook.name, entry);
+  const hookConfig = resolveHookConfig(config, hookKey);
+  const osList = entry.clawdbot?.os ?? [];
+  const remotePlatforms = eligibility?.remote?.platforms ?? [];
+
+  // Check if explicitly disabled
+  if (hookConfig?.enabled === false) return false;
+
+  // Check OS requirement
+  if (
+    osList.length > 0 &&
+    !osList.includes(resolveRuntimePlatform()) &&
+    !remotePlatforms.some((platform) => osList.includes(platform))
+  ) {
+    return false;
+  }
+
+  // If marked as 'always', bypass all other checks
+  if (entry.clawdbot?.always === true) {
+    return true;
+  }
+
+  // Check required binaries (all must be present)
+  const requiredBins = entry.clawdbot?.requires?.bins ?? [];
+  if (requiredBins.length > 0) {
+    for (const bin of requiredBins) {
+      if (hasBinary(bin)) continue;
+      if (eligibility?.remote?.hasBin?.(bin)) continue;
+      return false;
+    }
+  }
+
+  // Check anyBins (at least one must be present)
+  const requiredAnyBins = entry.clawdbot?.requires?.anyBins ?? [];
+  if (requiredAnyBins.length > 0) {
+    const anyFound =
+      requiredAnyBins.some((bin) => hasBinary(bin)) ||
+      eligibility?.remote?.hasAnyBin?.(requiredAnyBins);
+    if (!anyFound) return false;
+  }
+
+  // Check required environment variables
+  const requiredEnv = entry.clawdbot?.requires?.env ?? [];
+  if (requiredEnv.length > 0) {
+    for (const envName of requiredEnv) {
+      if (process.env[envName]) continue;
+      if (hookConfig?.env?.[envName]) continue;
+      return false;
+    }
+  }
+
+  // Check required config paths
+  const requiredConfig = entry.clawdbot?.requires?.config ?? [];
+  if (requiredConfig.length > 0) {
+    for (const configPath of requiredConfig) {
+      if (!isConfigPathTruthy(config, configPath)) return false;
+    }
+  }
+
+  return true;
+}
--- a/src/hooks/frontmatter.ts
+++ b/src/hooks/frontmatter.ts
@@ -0,0 +1,152 @@
+import type {
+  ClawdbotHookMetadata,
+  HookEntry,
+  HookInstallSpec,
+  HookInvocationPolicy,
+  ParsedHookFrontmatter,
+} from "./types.js";
+
+function stripQuotes(value: string): string {
+  if (
+    (value.startsWith('"') && value.endsWith('"')) ||
+    (value.startsWith("'") && value.endsWith("'"))
+  ) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+export function parseFrontmatter(content: string): ParsedHookFrontmatter {
+  const frontmatter: ParsedHookFrontmatter = {};
+  const normalized = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  if (!normalized.startsWith("---")) return frontmatter;
+  const endIndex = normalized.indexOf("\n---", 3);
+  if (endIndex === -1) return frontmatter;
+  const block = normalized.slice(4, endIndex);
+  for (const line of block.split("\n")) {
+    const match = line.match(/^([\w-]+):\s*(.*)$/);
+    if (!match) continue;
+    const key = match[1];
+    const value = stripQuotes(match[2].trim());
+    if (!key || !value) continue;
+    frontmatter[key] = value;
+  }
+  return frontmatter;
+}
+
+function normalizeStringList(input: unknown): string[] {
+  if (!input) return [];
+  if (Array.isArray(input)) {
+    return input.map((value) => String(value).trim()).filter(Boolean);
+  }
+  if (typeof input === "string") {
+    return input
+      .split(",")
+      .map((value) => value.trim())
+      .filter(Boolean);
+  }
+  return [];
+}
+
+function parseInstallSpec(input: unknown): HookInstallSpec | undefined {
+  if (!input || typeof input !== "object") return undefined;
+  const raw = input as Record<string, unknown>;
+  const kindRaw =
+    typeof raw.kind === "string" ? raw.kind : typeof raw.type === "string" ? raw.type : "";
+  const kind = kindRaw.trim().toLowerCase();
+  if (kind !== "bundled" && kind !== "npm" && kind !== "git") {
+    return undefined;
+  }
+
+  const spec: HookInstallSpec = {
+    kind: kind as HookInstallSpec["kind"],
+  };
+
+  if (typeof raw.id === "string") spec.id = raw.id;
+  if (typeof raw.label === "string") spec.label = raw.label;
+  const bins = normalizeStringList(raw.bins);
+  if (bins.length > 0) spec.bins = bins;
+  if (typeof raw.package === "string") spec.package = raw.package;
+  if (typeof raw.repository === "string") spec.repository = raw.repository;
+
+  return spec;
+}
+
+function getFrontmatterValue(frontmatter: ParsedHookFrontmatter, key: string): string | undefined {
+  const raw = frontmatter[key];
+  return typeof raw === "string" ? raw : undefined;
+}
+
+function parseFrontmatterBool(value: string | undefined, fallback: boolean): boolean {
+  if (!value) return fallback;
+  const normalized = value.trim().toLowerCase();
+  if (!normalized) return fallback;
+  if (normalized === "true" || normalized === "1" || normalized === "yes" || normalized === "on") {
+    return true;
+  }
+  if (
+    normalized === "false" ||
+    normalized === "0" ||
+    normalized === "no" ||
+    normalized === "off"
+  ) {
+    return false;
+  }
+  return fallback;
+}
+
+export function resolveClawdbotMetadata(
+  frontmatter: ParsedHookFrontmatter,
+): ClawdbotHookMetadata | undefined {
+  const raw = getFrontmatterValue(frontmatter, "metadata");
+  if (!raw) return undefined;
+  try {
+    const parsed = JSON.parse(raw) as { clawdbot?: unknown };
+    if (!parsed || typeof parsed !== "object") return undefined;
+    const clawdbot = (parsed as { clawdbot?: unknown }).clawdbot;
+    if (!clawdbot || typeof clawdbot !== "object") return undefined;
+    const clawdbotObj = clawdbot as Record<string, unknown>;
+    const requiresRaw =
+      typeof clawdbotObj.requires === "object" && clawdbotObj.requires !== null
+        ? (clawdbotObj.requires as Record<string, unknown>)
+        : undefined;
+    const installRaw = Array.isArray(clawdbotObj.install) ? (clawdbotObj.install as unknown[]) : [];
+    const install = installRaw
+      .map((entry) => parseInstallSpec(entry))
+      .filter((entry): entry is HookInstallSpec => Boolean(entry));
+    const osRaw = normalizeStringList(clawdbotObj.os);
+    const eventsRaw = normalizeStringList(clawdbotObj.events);
+    return {
+      always: typeof clawdbotObj.always === "boolean" ? clawdbotObj.always : undefined,
+      emoji: typeof clawdbotObj.emoji === "string" ? clawdbotObj.emoji : undefined,
+      homepage: typeof clawdbotObj.homepage === "string" ? clawdbotObj.homepage : undefined,
+      hookKey: typeof clawdbotObj.hookKey === "string" ? clawdbotObj.hookKey : undefined,
+      export: typeof clawdbotObj.export === "string" ? clawdbotObj.export : undefined,
+      os: osRaw.length > 0 ? osRaw : undefined,
+      events: eventsRaw.length > 0 ? eventsRaw : [],
+      requires: requiresRaw
+        ? {
+            bins: normalizeStringList(requiresRaw.bins),
+            anyBins: normalizeStringList(requiresRaw.anyBins),
+            env: normalizeStringList(requiresRaw.env),
+            config: normalizeStringList(requiresRaw.config),
+          }
+        : undefined,
+      install: install.length > 0 ? install : undefined,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+export function resolveHookInvocationPolicy(
+  frontmatter: ParsedHookFrontmatter,
+): HookInvocationPolicy {
+  return {
+    enabled: parseFrontmatterBool(getFrontmatterValue(frontmatter, "enabled"), true),
+  };
+}
+
+export function resolveHookKey(hookName: string, entry?: HookEntry): string {
+  return entry?.clawdbot?.hookKey ?? hookName;
+}
--- a/src/hooks/hooks-status.ts
+++ b/src/hooks/hooks-status.ts
@@ -0,0 +1,225 @@
+import path from "node:path";
+
+import type { ClawdbotConfig } from "../config/config.js";
+import { CONFIG_DIR } from "../utils.js";
+import {
+  hasBinary,
+  isConfigPathTruthy,
+  resolveConfigPath,
+  resolveHookConfig,
+} from "./config.js";
+import type {
+  HookEligibilityContext,
+  HookEntry,
+  HookInstallSpec,
+} from "./types.js";
+import { loadWorkspaceHookEntries } from "./workspace.js";
+
+export type HookStatusConfigCheck = {
+  path: string;
+  value: unknown;
+  satisfied: boolean;
+};
+
+export type HookInstallOption = {
+  id: string;
+  kind: HookInstallSpec["kind"];
+  label: string;
+  bins: string[];
+};
+
+export type HookStatusEntry = {
+  name: string;
+  description: string;
+  source: string;
+  filePath: string;
+  baseDir: string;
+  handlerPath: string;
+  hookKey: string;
+  emoji?: string;
+  homepage?: string;
+  events: string[];
+  always: boolean;
+  disabled: boolean;
+  eligible: boolean;
+  requirements: {
+    bins: string[];
+    anyBins: string[];
+    env: string[];
+    config: string[];
+    os: string[];
+  };
+  missing: {
+    bins: string[];
+    anyBins: string[];
+    env: string[];
+    config: string[];
+    os: string[];
+  };
+  configChecks: HookStatusConfigCheck[];
+  install: HookInstallOption[];
+};
+
+export type HookStatusReport = {
+  workspaceDir: string;
+  managedHooksDir: string;
+  hooks: HookStatusEntry[];
+};
+
+function resolveHookKey(entry: HookEntry): string {
+  return entry.clawdbot?.hookKey ?? entry.hook.name;
+}
+
+function normalizeInstallOptions(entry: HookEntry): HookInstallOption[] {
+  const install = entry.clawdbot?.install ?? [];
+  if (install.length === 0) return [];
+
+  // For hooks, we just list all install options
+  return install.map((spec, index) => {
+    const id = (spec.id ?? `${spec.kind}-${index}`).trim();
+    const bins = spec.bins ?? [];
+    let label = (spec.label ?? "").trim();
+
+    if (!label) {
+      if (spec.kind === "bundled") {
+        label = "Bundled with Clawdbot";
+      } else if (spec.kind === "npm" && spec.package) {
+        label = `Install ${spec.package} (npm)`;
+      } else if (spec.kind === "git" && spec.repository) {
+        label = `Install from ${spec.repository}`;
+      } else {
+        label = "Run installer";
+      }
+    }
+
+    return { id, kind: spec.kind, label, bins };
+  });
+}
+
+function buildHookStatus(
+  entry: HookEntry,
+  config?: ClawdbotConfig,
+  eligibility?: HookEligibilityContext,
+): HookStatusEntry {
+  const hookKey = resolveHookKey(entry);
+  const hookConfig = resolveHookConfig(config, hookKey);
+  const disabled = hookConfig?.enabled === false;
+  const always = entry.clawdbot?.always === true;
+  const emoji = entry.clawdbot?.emoji ?? entry.frontmatter.emoji;
+  const homepageRaw =
+    entry.clawdbot?.homepage ??
+    entry.frontmatter.homepage ??
+    entry.frontmatter.website ??
+    entry.frontmatter.url;
+  const homepage = homepageRaw?.trim() ? homepageRaw.trim() : undefined;
+  const events = entry.clawdbot?.events ?? [];
+
+  const requiredBins = entry.clawdbot?.requires?.bins ?? [];
+  const requiredAnyBins = entry.clawdbot?.requires?.anyBins ?? [];
+  const requiredEnv = entry.clawdbot?.requires?.env ?? [];
+  const requiredConfig = entry.clawdbot?.requires?.config ?? [];
+  const requiredOs = entry.clawdbot?.os ?? [];
+
+  const missingBins = requiredBins.filter((bin) => {
+    if (hasBinary(bin)) return false;
+    if (eligibility?.remote?.hasBin?.(bin)) return false;
+    return true;
+  });
+
+  const missingAnyBins =
+    requiredAnyBins.length > 0 &&
+    !(
+      requiredAnyBins.some((bin) => hasBinary(bin)) ||
+      eligibility?.remote?.hasAnyBin?.(requiredAnyBins)
+    )
+      ? requiredAnyBins
+      : [];
+
+  const missingOs =
+    requiredOs.length > 0 &&
+    !requiredOs.includes(process.platform) &&
+    !eligibility?.remote?.platforms?.some((platform) => requiredOs.includes(platform))
+      ? requiredOs
+      : [];
+
+  const missingEnv: string[] = [];
+  for (const envName of requiredEnv) {
+    if (process.env[envName]) continue;
+    if (hookConfig?.env?.[envName]) continue;
+    missingEnv.push(envName);
+  }
+
+  const configChecks: HookStatusConfigCheck[] = requiredConfig.map((pathStr) => {
+    const value = resolveConfigPath(config, pathStr);
+    const satisfied = isConfigPathTruthy(config, pathStr);
+    return { path: pathStr, value, satisfied };
+  });
+
+  const missingConfig = configChecks
+    .filter((check) => !check.satisfied)
+    .map((check) => check.path);
+
+  const missing = always
+    ? { bins: [], anyBins: [], env: [], config: [], os: [] }
+    : {
+        bins: missingBins,
+        anyBins: missingAnyBins,
+        env: missingEnv,
+        config: missingConfig,
+        os: missingOs,
+      };
+
+  const eligible =
+    !disabled &&
+    (always ||
+      (missing.bins.length === 0 &&
+        missing.anyBins.length === 0 &&
+        missing.env.length === 0 &&
+        missing.config.length === 0 &&
+        missing.os.length === 0));
+
+  return {
+    name: entry.hook.name,
+    description: entry.hook.description,
+    source: entry.hook.source,
+    filePath: entry.hook.filePath,
+    baseDir: entry.hook.baseDir,
+    handlerPath: entry.hook.handlerPath,
+    hookKey,
+    emoji,
+    homepage,
+    events,
+    always,
+    disabled,
+    eligible,
+    requirements: {
+      bins: requiredBins,
+      anyBins: requiredAnyBins,
+      env: requiredEnv,
+      config: requiredConfig,
+      os: requiredOs,
+    },
+    missing,
+    configChecks,
+    install: normalizeInstallOptions(entry),
+  };
+}
+
+export function buildWorkspaceHookStatus(
+  workspaceDir: string,
+  opts?: {
+    config?: ClawdbotConfig;
+    managedHooksDir?: string;
+    entries?: HookEntry[];
+    eligibility?: HookEligibilityContext;
+  },
+): HookStatusReport {
+  const managedHooksDir = opts?.managedHooksDir ?? path.join(CONFIG_DIR, "hooks");
+  const hookEntries = opts?.entries ?? loadWorkspaceHookEntries(workspaceDir, opts);
+
+  return {
+    workspaceDir,
+    managedHooksDir,
+    hooks: hookEntries.map((entry) => buildHookStatus(entry, opts?.config, opts?.eligibility)),
+  };
+}
--- a/src/hooks/internal-hooks.test.ts
+++ b/src/hooks/internal-hooks.test.ts
@@ -0,0 +1,229 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  clearInternalHooks,
+  createInternalHookEvent,
+  getRegisteredEventKeys,
+  registerInternalHook,
+  triggerInternalHook,
+  unregisterInternalHook,
+  type InternalHookEvent,
+} from './internal-hooks.js';
+
+describe('internal-hooks', () => {
+  beforeEach(() => {
+    clearInternalHooks();
+  });
+
+  afterEach(() => {
+    clearInternalHooks();
+  });
+
+  describe('registerInternalHook', () => {
+    it('should register a hook handler', () => {
+      const handler = vi.fn();
+      registerInternalHook('command:new', handler);
+
+      const keys = getRegisteredEventKeys();
+      expect(keys).toContain('command:new');
+    });
+
+    it('should allow multiple handlers for the same event', () => {
+      const handler1 = vi.fn();
+      const handler2 = vi.fn();
+
+      registerInternalHook('command:new', handler1);
+      registerInternalHook('command:new', handler2);
+
+      const keys = getRegisteredEventKeys();
+      expect(keys).toContain('command:new');
+    });
+  });
+
+  describe('unregisterInternalHook', () => {
+    it('should unregister a specific handler', () => {
+      const handler1 = vi.fn();
+      const handler2 = vi.fn();
+
+      registerInternalHook('command:new', handler1);
+      registerInternalHook('command:new', handler2);
+
+      unregisterInternalHook('command:new', handler1);
+
+      const event = createInternalHookEvent('command', 'new', 'test-session');
+      void triggerInternalHook(event);
+
+      expect(handler1).not.toHaveBeenCalled();
+      expect(handler2).toHaveBeenCalled();
+    });
+
+    it('should clean up empty handler arrays', () => {
+      const handler = vi.fn();
+
+      registerInternalHook('command:new', handler);
+      unregisterInternalHook('command:new', handler);
+
+      const keys = getRegisteredEventKeys();
+      expect(keys).not.toContain('command:new');
+    });
+  });
+
+  describe('triggerInternalHook', () => {
+    it('should trigger handlers for general event type', async () => {
+      const handler = vi.fn();
+      registerInternalHook('command', handler);
+
+      const event = createInternalHookEvent('command', 'new', 'test-session');
+      await triggerInternalHook(event);
+
+      expect(handler).toHaveBeenCalledWith(event);
+    });
+
+    it('should trigger handlers for specific event action', async () => {
+      const handler = vi.fn();
+      registerInternalHook('command:new', handler);
+
+      const event = createInternalHookEvent('command', 'new', 'test-session');
+      await triggerInternalHook(event);
+
+      expect(handler).toHaveBeenCalledWith(event);
+    });
+
+    it('should trigger both general and specific handlers', async () => {
+      const generalHandler = vi.fn();
+      const specificHandler = vi.fn();
+
+      registerInternalHook('command', generalHandler);
+      registerInternalHook('command:new', specificHandler);
+
+      const event = createInternalHookEvent('command', 'new', 'test-session');
+      await triggerInternalHook(event);
+
+      expect(generalHandler).toHaveBeenCalledWith(event);
+      expect(specificHandler).toHaveBeenCalledWith(event);
+    });
+
+    it('should handle async handlers', async () => {
+      const handler = vi.fn(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 10));
+      });
+
+      registerInternalHook('command:new', handler);
+
+      const event = createInternalHookEvent('command', 'new', 'test-session');
+      await triggerInternalHook(event);
+
+      expect(handler).toHaveBeenCalledWith(event);
+    });
+
+    it('should catch and log errors from handlers', async () => {
+      const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {});
+      const errorHandler = vi.fn(() => {
+        throw new Error('Handler failed');
+      });
+      const successHandler = vi.fn();
+
+      registerInternalHook('command:new', errorHandler);
+      registerInternalHook('command:new', successHandler);
+
+      const event = createInternalHookEvent('command', 'new', 'test-session');
+      await triggerInternalHook(event);
+
+      expect(errorHandler).toHaveBeenCalled();
+      expect(successHandler).toHaveBeenCalled();
+      expect(consoleError).toHaveBeenCalledWith(
+        expect.stringContaining('Internal hook error'),
+        expect.stringContaining('Handler failed')
+      );
+
+      consoleError.mockRestore();
+    });
+
+    it('should not throw if no handlers are registered', async () => {
+      const event = createInternalHookEvent('command', 'new', 'test-session');
+      await expect(triggerInternalHook(event)).resolves.not.toThrow();
+    });
+  });
+
+  describe('createInternalHookEvent', () => {
+    it('should create a properly formatted event', () => {
+      const event = createInternalHookEvent('command', 'new', 'test-session', {
+        foo: 'bar',
+      });
+
+      expect(event.type).toBe('command');
+      expect(event.action).toBe('new');
+      expect(event.sessionKey).toBe('test-session');
+      expect(event.context).toEqual({ foo: 'bar' });
+      expect(event.timestamp).toBeInstanceOf(Date);
+    });
+
+    it('should use empty context if not provided', () => {
+      const event = createInternalHookEvent('command', 'new', 'test-session');
+
+      expect(event.context).toEqual({});
+    });
+  });
+
+  describe('getRegisteredEventKeys', () => {
+    it('should return all registered event keys', () => {
+      registerInternalHook('command:new', vi.fn());
+      registerInternalHook('command:stop', vi.fn());
+      registerInternalHook('session:start', vi.fn());
+
+      const keys = getRegisteredEventKeys();
+      expect(keys).toContain('command:new');
+      expect(keys).toContain('command:stop');
+      expect(keys).toContain('session:start');
+    });
+
+    it('should return empty array when no handlers are registered', () => {
+      const keys = getRegisteredEventKeys();
+      expect(keys).toEqual([]);
+    });
+  });
+
+  describe('clearInternalHooks', () => {
+    it('should remove all registered handlers', () => {
+      registerInternalHook('command:new', vi.fn());
+      registerInternalHook('command:stop', vi.fn());
+
+      clearInternalHooks();
+
+      const keys = getRegisteredEventKeys();
+      expect(keys).toEqual([]);
+    });
+  });
+
+  describe('integration', () => {
+    it('should handle a complete hook lifecycle', async () => {
+      const results: InternalHookEvent[] = [];
+      const handler = vi.fn((event: InternalHookEvent) => {
+        results.push(event);
+      });
+
+      // Register
+      registerInternalHook('command:new', handler);
+
+      // Trigger
+      const event1 = createInternalHookEvent('command', 'new', 'session-1');
+      await triggerInternalHook(event1);
+
+      const event2 = createInternalHookEvent('command', 'new', 'session-2');
+      await triggerInternalHook(event2);
+
+      // Verify
+      expect(results).toHaveLength(2);
+      expect(results[0].sessionKey).toBe('session-1');
+      expect(results[1].sessionKey).toBe('session-2');
+
+      // Unregister
+      unregisterInternalHook('command:new', handler);
+
+      // Trigger again - should not call handler
+      const event3 = createInternalHookEvent('command', 'new', 'session-3');
+      await triggerInternalHook(event3);
+
+      expect(results).toHaveLength(2);
+    });
+  });
+});
--- a/src/hooks/internal-hooks.ts
+++ b/src/hooks/internal-hooks.ts
@@ -0,0 +1,155 @@
+/**
+ * Internal hook system for clawdbot agent events
+ *
+ * Provides an extensible event-driven hook system for internal agent events
+ * like command processing, session lifecycle, etc.
+ */
+
+export type InternalHookEventType = 'command' | 'session' | 'agent';
+
+export interface InternalHookEvent {
+  /** The type of event (command, session, agent, etc.) */
+  type: InternalHookEventType;
+  /** The specific action within the type (e.g., 'new', 'reset', 'stop') */
+  action: string;
+  /** The session key this event relates to */
+  sessionKey: string;
+  /** Additional context specific to the event */
+  context: Record<string, unknown>;
+  /** Timestamp when the event occurred */
+  timestamp: Date;
+  /** Messages to send back to the user (hooks can push to this array) */
+  messages: string[];
+}
+
+export type InternalHookHandler = (event: InternalHookEvent) => Promise<void> | void;
+
+/** Registry of hook handlers by event key */
+const handlers = new Map<string, InternalHookHandler[]>();
+
+/**
+ * Register a hook handler for a specific event type or event:action combination
+ *
+ * @param eventKey - Event type (e.g., 'command') or specific action (e.g., 'command:new')
+ * @param handler - Function to call when the event is triggered
+ *
+ * @example
+ * ```ts
+ * // Listen to all command events
+ * registerInternalHook('command', async (event) => {
+ *   console.log('Command:', event.action);
+ * });
+ *
+ * // Listen only to /new commands
+ * registerInternalHook('command:new', async (event) => {
+ *   await saveSessionToMemory(event);
+ * });
+ * ```
+ */
+export function registerInternalHook(
+  eventKey: string,
+  handler: InternalHookHandler
+): void {
+  if (!handlers.has(eventKey)) {
+    handlers.set(eventKey, []);
+  }
+  handlers.get(eventKey)!.push(handler);
+}
+
+/**
+ * Unregister a specific hook handler
+ *
+ * @param eventKey - Event key the handler was registered for
+ * @param handler - The handler function to remove
+ */
+export function unregisterInternalHook(
+  eventKey: string,
+  handler: InternalHookHandler
+): void {
+  const eventHandlers = handlers.get(eventKey);
+  if (!eventHandlers) {
+    return;
+  }
+
+  const index = eventHandlers.indexOf(handler);
+  if (index !== -1) {
+    eventHandlers.splice(index, 1);
+  }
+
+  // Clean up empty handler arrays
+  if (eventHandlers.length === 0) {
+    handlers.delete(eventKey);
+  }
+}
+
+/**
+ * Clear all registered hooks (useful for testing)
+ */
+export function clearInternalHooks(): void {
+  handlers.clear();
+}
+
+/**
+ * Get all registered event keys (useful for debugging)
+ */
+export function getRegisteredEventKeys(): string[] {
+  return Array.from(handlers.keys());
+}
+
+/**
+ * Trigger an internal hook event
+ *
+ * Calls all handlers registered for:
+ * 1. The general event type (e.g., 'command')
+ * 2. The specific event:action combination (e.g., 'command:new')
+ *
+ * Handlers are called in registration order. Errors are caught and logged
+ * but don't prevent other handlers from running.
+ *
+ * @param event - The event to trigger
+ */
+export async function triggerInternalHook(event: InternalHookEvent): Promise<void> {
+  const typeHandlers = handlers.get(event.type) ?? [];
+  const specificHandlers = handlers.get(`${event.type}:${event.action}`) ?? [];
+
+  const allHandlers = [...typeHandlers, ...specificHandlers];
+
+  if (allHandlers.length === 0) {
+    return;
+  }
+
+  for (const handler of allHandlers) {
+    try {
+      await handler(event);
+    } catch (err) {
+      console.error(
+        `Internal hook error [${event.type}:${event.action}]:`,
+        err instanceof Error ? err.message : String(err)
+      );
+    }
+  }
+}
+
+/**
+ * Create an internal hook event with common fields filled in
+ *
+ * @param type - The event type
+ * @param action - The action within that type
+ * @param sessionKey - The session key
+ * @param context - Additional context
+ */
+export function createInternalHookEvent(
+  type: InternalHookEventType,
+  action: string,
+  sessionKey: string,
+  context: Record<string, unknown> = {}
+): InternalHookEvent {
+  return {
+    type,
+    action,
+    sessionKey,
+    context,
+    timestamp: new Date(),
+    messages: [],
+  };
+}
--- a/src/hooks/llm-slug-generator.ts
+++ b/src/hooks/llm-slug-generator.ts
@@ -0,0 +1,80 @@
+/**
+ * LLM-based slug generator for session memory filenames
+ */
+
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { runEmbeddedPiAgent } from '../agents/pi-embedded.js';
+import type { ClawdbotConfig } from '../config/config.js';
+import { resolveDefaultAgentId, resolveAgentWorkspaceDir, resolveAgentDir } from '../agents/agent-scope.js';
+
+/**
+ * Generate a short 1-2 word filename slug from session content using LLM
+ */
+export async function generateSlugViaLLM(params: {
+  sessionContent: string;
+  cfg: ClawdbotConfig;
+}): Promise<string | null> {
+  let tempSessionFile: string | null = null;
+
+  try {
+    const agentId = resolveDefaultAgentId(params.cfg);
+    const workspaceDir = resolveAgentWorkspaceDir(params.cfg, agentId);
+    const agentDir = resolveAgentDir(params.cfg, agentId);
+
+    // Create a temporary session file for this one-off LLM call
+    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'clawdbot-slug-'));
+    tempSessionFile = path.join(tempDir, 'session.jsonl');
+
+    const prompt = `Based on this conversation, generate a short 1-2 word filename slug (lowercase, hyphen-separated, no file extension).
+
+Conversation summary:
+${params.sessionContent.slice(0, 2000)}
+
+Reply with ONLY the slug, nothing else. Examples: "vendor-pitch", "api-design", "bug-fix"`;
+
+    const result = await runEmbeddedPiAgent({
+      sessionId: `slug-generator-${Date.now()}`,
+      sessionKey: 'temp:slug-generator',
+      sessionFile: tempSessionFile,
+      workspaceDir,
+      agentDir,
+      config: params.cfg,
+      prompt,
+      timeoutMs: 15_000, // 15 second timeout
+      runId: `slug-gen-${Date.now()}`,
+    });
+
+    // Extract text from payloads
+    if (result.payloads && result.payloads.length > 0) {
+      const text = result.payloads[0]?.text;
+      if (text) {
+        // Clean up the response - extract just the slug
+        const slug = text
+          .trim()
+          .toLowerCase()
+          .replace(/[^a-z0-9-]/g, '-')
+          .replace(/-+/g, '-')
+          .replace(/^-|-$/g, '')
+          .slice(0, 30); // Max 30 chars
+
+        return slug || null;
+      }
+    }
+
+    return null;
+  } catch (err) {
+    console.error('[llm-slug-generator] Failed to generate slug:', err);
+    return null;
+  } finally {
+    // Clean up temporary session file
+    if (tempSessionFile) {
+      try {
+        await fs.rm(path.dirname(tempSessionFile), { recursive: true, force: true });
+      } catch {
+        // Ignore cleanup errors
+      }
+    }
+  }
+}
--- a/src/hooks/loader.test.ts
+++ b/src/hooks/loader.test.ts
@@ -0,0 +1,271 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { loadInternalHooks } from './loader.js';
+import { clearInternalHooks, getRegisteredEventKeys, triggerInternalHook, createInternalHookEvent } from './internal-hooks.js';
+import type { ClawdbotConfig } from '../config/config.js';
+
+describe('loader', () => {
+  let tmpDir: string;
+  let originalBundledDir: string | undefined;
+
+  beforeEach(async () => {
+    clearInternalHooks();
+    // Create a temp directory for test modules
+    tmpDir = path.join(os.tmpdir(), `clawdbot-test-${Date.now()}`);
+    await fs.mkdir(tmpDir, { recursive: true });
+
+    // Disable bundled hooks during tests by setting env var to non-existent directory
+    originalBundledDir = process.env.CLAWDBOT_BUNDLED_HOOKS_DIR;
+    process.env.CLAWDBOT_BUNDLED_HOOKS_DIR = '/nonexistent/bundled/hooks';
+  });
+
+  afterEach(async () => {
+    clearInternalHooks();
+    // Restore original env var
+    if (originalBundledDir === undefined) {
+      delete process.env.CLAWDBOT_BUNDLED_HOOKS_DIR;
+    } else {
+      process.env.CLAWDBOT_BUNDLED_HOOKS_DIR = originalBundledDir;
+    }
+    // Clean up temp directory
+    try {
+      await fs.rm(tmpDir, { recursive: true, force: true });
+    } catch {
+      // Ignore cleanup errors
+    }
+  });
+
+  describe('loadInternalHooks', () => {
+    it('should return 0 when internal hooks are not enabled', async () => {
+      const cfg: ClawdbotConfig = {
+        hooks: {
+          internal: {
+            enabled: false,
+          },
+        },
+      };
+
+      const count = await loadInternalHooks(cfg, tmpDir);
+      expect(count).toBe(0);
+    });
+
+    it('should return 0 when hooks config is missing', async () => {
+      const cfg: ClawdbotConfig = {};
+      const count = await loadInternalHooks(cfg, tmpDir);
+      expect(count).toBe(0);
+    });
+
+    it('should load a handler from a module', async () => {
+      // Create a test handler module
+      const handlerPath = path.join(tmpDir, 'test-handler.js');
+      const handlerCode = `
+        export default async function(event) {
+          // Test handler
+        }
+      `;
+      await fs.writeFile(handlerPath, handlerCode, 'utf-8');
+
+      const cfg: ClawdbotConfig = {
+        hooks: {
+          internal: {
+            enabled: true,
+            handlers: [
+              {
+                event: 'command:new',
+                module: handlerPath,
+              },
+            ],
+          },
+        },
+      };
+
+      const count = await loadInternalHooks(cfg, tmpDir);
+      expect(count).toBe(1);
+
+      const keys = getRegisteredEventKeys();
+      expect(keys).toContain('command:new');
+    });
+
+    it('should load multiple handlers', async () => {
+      // Create test handler modules
+      const handler1Path = path.join(tmpDir, 'handler1.js');
+      const handler2Path = path.join(tmpDir, 'handler2.js');
+
+      await fs.writeFile(handler1Path, 'export default async function() {}', 'utf-8');
+      await fs.writeFile(handler2Path, 'export default async function() {}', 'utf-8');
+
+      const cfg: ClawdbotConfig = {
+        hooks: {
+          internal: {
+            enabled: true,
+            handlers: [
+              { event: 'command:new', module: handler1Path },
+              { event: 'command:stop', module: handler2Path },
+            ],
+          },
+        },
+      };
+
+      const count = await loadInternalHooks(cfg, tmpDir);
+      expect(count).toBe(2);
+
+      const keys = getRegisteredEventKeys();
+      expect(keys).toContain('command:new');
+      expect(keys).toContain('command:stop');
+    });
+
+    it('should support named exports', async () => {
+      // Create a handler module with named export
+      const handlerPath = path.join(tmpDir, 'named-export.js');
+      const handlerCode = `
+        export const myHandler = async function(event) {
+          // Named export handler
+        }
+      `;
+      await fs.writeFile(handlerPath, handlerCode, 'utf-8');
+
+      const cfg: ClawdbotConfig = {
+        hooks: {
+          internal: {
+            enabled: true,
+            handlers: [
+              {
+                event: 'command:new',
+                module: handlerPath,
+                export: 'myHandler',
+              },
+            ],
+          },
+        },
+      };
+
+      const count = await loadInternalHooks(cfg, tmpDir);
+      expect(count).toBe(1);
+    });
+
+    it('should handle module loading errors gracefully', async () => {
+      const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+      const cfg: ClawdbotConfig = {
+        hooks: {
+          internal: {
+            enabled: true,
+            handlers: [
+              {
+                event: 'command:new',
+                module: '/nonexistent/path/handler.js',
+              },
+            ],
+          },
+        },
+      };
+
+      const count = await loadInternalHooks(cfg, tmpDir);
+      expect(count).toBe(0);
+      expect(consoleError).toHaveBeenCalledWith(
+        expect.stringContaining('Failed to load internal hook handler'),
+        expect.any(String)
+      );
+
+      consoleError.mockRestore();
+    });
+
+    it('should handle non-function exports', async () => {
+      const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+      // Create a module with a non-function export
+      const handlerPath = path.join(tmpDir, 'bad-export.js');
+      await fs.writeFile(handlerPath, 'export default "not a function";', 'utf-8');
+
+      const cfg: ClawdbotConfig = {
+        hooks: {
+          internal: {
+            enabled: true,
+            handlers: [
+              {
+                event: 'command:new',
+                module: handlerPath,
+              },
+            ],
+          },
+        },
+      };
+
+      const count = await loadInternalHooks(cfg, tmpDir);
+      expect(count).toBe(0);
+      expect(consoleError).toHaveBeenCalledWith(
+        expect.stringContaining('is not a function')
+      );
+
+      consoleError.mockRestore();
+    });
+
+    it('should handle relative paths', async () => {
+      // Create a handler module
+      const handlerPath = path.join(tmpDir, 'relative-handler.js');
+      await fs.writeFile(handlerPath, 'export default async function() {}', 'utf-8');
+
+      // Get relative path from cwd
+      const relativePath = path.relative(process.cwd(), handlerPath);
+
+      const cfg: ClawdbotConfig = {
+        hooks: {
+          internal: {
+            enabled: true,
+            handlers: [
+              {
+                event: 'command:new',
+                module: relativePath,
+              },
+            ],
+          },
+        },
+      };
+
+      const count = await loadInternalHooks(cfg, tmpDir);
+      expect(count).toBe(1);
+    });
+
+    it('should actually call the loaded handler', async () => {
+      // Create a handler that we can verify was called
+      const handlerPath = path.join(tmpDir, 'callable-handler.js');
+      const handlerCode = `
+        let callCount = 0;
+        export default async function(event) {
+          callCount++;
+        }
+        export function getCallCount() {
+          return callCount;
+        }
+      `;
+      await fs.writeFile(handlerPath, handlerCode, 'utf-8');
+
+      const cfg: ClawdbotConfig = {
+        hooks: {
+          internal: {
+            enabled: true,
+            handlers: [
+              {
+                event: 'command:new',
+                module: handlerPath,
+              },
+            ],
+          },
+        },
+      };
+
+      await loadInternalHooks(cfg, tmpDir);
+
+      // Trigger the hook
+      const event = createInternalHookEvent('command', 'new', 'test-session');
+      await triggerInternalHook(event);
+
+      // The handler should have been called, but we can't directly verify
+      // the call count from this context without more complex test infrastructure
+      // This test mainly verifies that loading and triggering doesn't crash
+      expect(getRegisteredEventKeys()).toContain('command:new');
+    });
+  });
+});
--- a/src/hooks/loader.ts
+++ b/src/hooks/loader.ts
@@ -0,0 +1,152 @@
+/**
+ * Dynamic loader for internal hook handlers
+ *
+ * Loads hook handlers from external modules based on configuration
+ * and from directory-based discovery (bundled, managed, workspace)
+ */
+
+import { pathToFileURL } from 'node:url';
+import path from 'node:path';
+import { registerInternalHook } from './internal-hooks.js';
+import type { ClawdbotConfig } from '../config/config.js';
+import type { InternalHookHandler } from './internal-hooks.js';
+import { loadWorkspaceHookEntries } from './workspace.js';
+import { resolveHookConfig } from './config.js';
+import { shouldIncludeHook } from './config.js';
+
+/**
+ * Load and register all internal hook handlers
+ *
+ * Loads hooks from both:
+ * 1. Directory-based discovery (bundled, managed, workspace)
+ * 2. Legacy config handlers (backwards compatibility)
+ *
+ * @param cfg - Clawdbot configuration
+ * @param workspaceDir - Workspace directory for hook discovery
+ * @returns Number of handlers successfully loaded
+ *
+ * @example
+ * ```ts
+ * const config = await loadConfig();
+ * const workspaceDir = resolveAgentWorkspaceDir(config, agentId);
+ * const count = await loadInternalHooks(config, workspaceDir);
+ * console.log(`Loaded ${count} internal hook handlers`);
+ * ```
+ */
+export async function loadInternalHooks(
+  cfg: ClawdbotConfig,
+  workspaceDir: string,
+): Promise<number> {
+  // Check if internal hooks are enabled
+  if (!cfg.hooks?.internal?.enabled) {
+    return 0;
+  }
+
+  let loadedCount = 0;
+
+  // 1. Load hooks from directories (new system)
+  try {
+    const hookEntries = loadWorkspaceHookEntries(workspaceDir, { config: cfg });
+
+    // Filter by eligibility
+    const eligible = hookEntries.filter((entry) =>
+      shouldIncludeHook({ entry, config: cfg }),
+    );
+
+    for (const entry of eligible) {
+      const hookConfig = resolveHookConfig(cfg, entry.hook.name);
+
+      // Skip if explicitly disabled in config
+      if (hookConfig?.enabled === false) {
+        continue;
+      }
+
+      try {
+        // Import handler module with cache-busting
+        const url = pathToFileURL(entry.hook.handlerPath).href;
+        const cacheBustedUrl = `${url}?t=${Date.now()}`;
+        const mod = (await import(cacheBustedUrl)) as Record<string, unknown>;
+
+        // Get handler function (default or named export)
+        const exportName = entry.clawdbot?.export ?? 'default';
+        const handler = mod[exportName];
+
+        if (typeof handler !== 'function') {
+          console.error(
+            `Internal hook error: Handler '${exportName}' from ${entry.hook.name} is not a function`,
+          );
+          continue;
+        }
+
+        // Register for all events listed in metadata
+        const events = entry.clawdbot?.events ?? [];
+        if (events.length === 0) {
+          console.warn(
+            `Internal hook warning: Hook '${entry.hook.name}' has no events defined in metadata`,
+          );
+          continue;
+        }
+
+        for (const event of events) {
+          registerInternalHook(event, handler as InternalHookHandler);
+        }
+
+        console.log(
+          `Registered internal hook: ${entry.hook.name} -> ${events.join(', ')}${exportName !== 'default' ? ` (export: ${exportName})` : ''}`,
+        );
+        loadedCount++;
+      } catch (err) {
+        console.error(
+          `Failed to load internal hook ${entry.hook.name}:`,
+          err instanceof Error ? err.message : String(err),
+        );
+      }
+    }
+  } catch (err) {
+    console.error(
+      'Failed to load directory-based hooks:',
+      err instanceof Error ? err.message : String(err),
+    );
+  }
+
+  // 2. Load legacy config handlers (backwards compatibility)
+  const handlers = cfg.hooks.internal.handlers ?? [];
+  for (const handlerConfig of handlers) {
+    try {
+      // Resolve module path (absolute or relative to cwd)
+      const modulePath = path.isAbsolute(handlerConfig.module)
+        ? handlerConfig.module
+        : path.join(process.cwd(), handlerConfig.module);
+
+      // Import the module with cache-busting to ensure fresh reload
+      const url = pathToFileURL(modulePath).href;
+      const cacheBustedUrl = `${url}?t=${Date.now()}`;
+      const mod = (await import(cacheBustedUrl)) as Record<string, unknown>;
+
+      // Get the handler function
+      const exportName = handlerConfig.export ?? 'default';
+      const handler = mod[exportName];
+
+      if (typeof handler !== 'function') {
+        console.error(
+          `Internal hook error: Handler '${exportName}' from ${modulePath} is not a function`,
+        );
+        continue;
+      }
+
+      // Register the handler
+      registerInternalHook(handlerConfig.event, handler as InternalHookHandler);
+      console.log(
+        `Registered internal hook (legacy): ${handlerConfig.event} -> ${modulePath}${exportName !== 'default' ? `#${exportName}` : ''}`,
+      );
+      loadedCount++;
+    } catch (err) {
+      console.error(
+        `Failed to load internal hook handler from ${handlerConfig.module}:`,
+        err instanceof Error ? err.message : String(err),
+      );
+    }
+  }
+
+  return loadedCount;
+}
--- a/src/hooks/types.ts
+++ b/src/hooks/types.ts
@@ -0,0 +1,64 @@
+export type HookInstallSpec = {
+  id?: string;
+  kind: "bundled" | "npm" | "git";
+  label?: string;
+  package?: string;
+  repository?: string;
+  bins?: string[];
+};
+
+export type ClawdbotHookMetadata = {
+  always?: boolean;
+  hookKey?: string;
+  emoji?: string;
+  homepage?: string;
+  /** Events this hook handles (e.g., ["command:new", "session:start"]) */
+  events: string[];
+  /** Optional export name (default: "default") */
+  export?: string;
+  os?: string[];
+  requires?: {
+    bins?: string[];
+    anyBins?: string[];
+    env?: string[];
+    config?: string[];
+  };
+  install?: HookInstallSpec[];
+};
+
+export type HookInvocationPolicy = {
+  enabled: boolean;
+};
+
+export type ParsedHookFrontmatter = Record<string, string>;
+
+export type Hook = {
+  name: string;
+  description: string;
+  source: "clawdbot-bundled" | "clawdbot-managed" | "clawdbot-workspace";
+  filePath: string; // Path to HOOK.md
+  baseDir: string; // Directory containing hook
+  handlerPath: string; // Path to handler module (handler.ts/js)
+};
+
+export type HookEntry = {
+  hook: Hook;
+  frontmatter: ParsedHookFrontmatter;
+  clawdbot?: ClawdbotHookMetadata;
+  invocation?: HookInvocationPolicy;
+};
+
+export type HookEligibilityContext = {
+  remote?: {
+    platforms: string[];
+    hasBin: (bin: string) => boolean;
+    hasAnyBin: (bins: string[]) => boolean;
+    note?: string;
+  };
+};
+
+export type HookSnapshot = {
+  hooks: Array<{ name: string; events: string[] }>;
+  resolvedHooks?: Hook[];
+  version?: number;
+};
--- a/src/hooks/workspace.ts
+++ b/src/hooks/workspace.ts
@@ -0,0 +1,197 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import type { ClawdbotConfig } from "../config/config.js";
+import { CONFIG_DIR, resolveUserPath } from "../utils.js";
+import { resolveBundledHooksDir } from "./bundled-dir.js";
+import { shouldIncludeHook } from "./config.js";
+import {
+  parseFrontmatter,
+  resolveClawdbotMetadata,
+  resolveHookInvocationPolicy,
+} from "./frontmatter.js";
+import type {
+  Hook,
+  HookEligibilityContext,
+  HookEntry,
+  HookSnapshot,
+  ParsedHookFrontmatter,
+} from "./types.js";
+
+function filterHookEntries(
+  entries: HookEntry[],
+  config?: ClawdbotConfig,
+  eligibility?: HookEligibilityContext,
+): HookEntry[] {
+  return entries.filter((entry) => shouldIncludeHook({ entry, config, eligibility }));
+}
+
+/**
+ * Scan a directory for hooks (subdirectories containing HOOK.md)
+ */
+function loadHooksFromDir(params: { dir: string; source: string }): Hook[] {
+  const { dir, source } = params;
+
+  // Check if directory exists
+  if (!fs.existsSync(dir)) return [];
+
+  const stat = fs.statSync(dir);
+  if (!stat.isDirectory()) return [];
+
+  const hooks: Hook[] = [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+
+    const hookDir = path.join(dir, entry.name);
+    const hookMdPath = path.join(hookDir, "HOOK.md");
+
+    // Skip if no HOOK.md file
+    if (!fs.existsSync(hookMdPath)) continue;
+
+    try {
+      // Read HOOK.md to extract name and description
+      const content = fs.readFileSync(hookMdPath, "utf-8");
+      const frontmatter = parseFrontmatter(content);
+
+      const name = frontmatter.name || entry.name;
+      const description = frontmatter.description || "";
+
+      // Locate handler file (handler.ts, handler.js, index.ts, index.js)
+      const handlerCandidates = [
+        "handler.ts",
+        "handler.js",
+        "index.ts",
+        "index.js",
+      ];
+
+      let handlerPath: string | undefined;
+      for (const candidate of handlerCandidates) {
+        const candidatePath = path.join(hookDir, candidate);
+        if (fs.existsSync(candidatePath)) {
+          handlerPath = candidatePath;
+          break;
+        }
+      }
+
+      // Skip if no handler file found
+      if (!handlerPath) {
+        console.warn(`[hooks] Hook "${name}" has HOOK.md but no handler file in ${hookDir}`);
+        continue;
+      }
+
+      hooks.push({
+        name,
+        description,
+        source: source as Hook["source"],
+        filePath: hookMdPath,
+        baseDir: hookDir,
+        handlerPath,
+      });
+    } catch (err) {
+      console.warn(`[hooks] Failed to load hook from ${hookDir}:`, err);
+      continue;
+    }
+  }
+
+  return hooks;
+}
+
+function loadHookEntries(
+  workspaceDir: string,
+  opts?: {
+    config?: ClawdbotConfig;
+    managedHooksDir?: string;
+    bundledHooksDir?: string;
+  },
+): HookEntry[] {
+  const managedHooksDir = opts?.managedHooksDir ?? path.join(CONFIG_DIR, "hooks");
+  const workspaceHooksDir = path.join(workspaceDir, "hooks");
+  const bundledHooksDir = opts?.bundledHooksDir ?? resolveBundledHooksDir();
+  const extraDirsRaw = opts?.config?.hooks?.internal?.load?.extraDirs ?? [];
+  const extraDirs = extraDirsRaw
+    .map((d) => (typeof d === "string" ? d.trim() : ""))
+    .filter(Boolean);
+
+  const bundledHooks = bundledHooksDir
+    ? loadHooksFromDir({
+        dir: bundledHooksDir,
+        source: "clawdbot-bundled",
+      })
+    : [];
+  const extraHooks = extraDirs.flatMap((dir) => {
+    const resolved = resolveUserPath(dir);
+    return loadHooksFromDir({
+      dir: resolved,
+      source: "clawdbot-workspace", // Extra dirs treated as workspace
+    });
+  });
+  const managedHooks = loadHooksFromDir({
+    dir: managedHooksDir,
+    source: "clawdbot-managed",
+  });
+  const workspaceHooks = loadHooksFromDir({
+    dir: workspaceHooksDir,
+    source: "clawdbot-workspace",
+  });
+
+  const merged = new Map<string, Hook>();
+  // Precedence: extra < bundled < managed < workspace (workspace wins)
+  for (const hook of extraHooks) merged.set(hook.name, hook);
+  for (const hook of bundledHooks) merged.set(hook.name, hook);
+  for (const hook of managedHooks) merged.set(hook.name, hook);
+  for (const hook of workspaceHooks) merged.set(hook.name, hook);
+
+  const hookEntries: HookEntry[] = Array.from(merged.values()).map((hook) => {
+    let frontmatter: ParsedHookFrontmatter = {};
+    try {
+      const raw = fs.readFileSync(hook.filePath, "utf-8");
+      frontmatter = parseFrontmatter(raw);
+    } catch {
+      // ignore malformed hooks
+    }
+    return {
+      hook,
+      frontmatter,
+      clawdbot: resolveClawdbotMetadata(frontmatter),
+      invocation: resolveHookInvocationPolicy(frontmatter),
+    };
+  });
+  return hookEntries;
+}
+
+export function buildWorkspaceHookSnapshot(
+  workspaceDir: string,
+  opts?: {
+    config?: ClawdbotConfig;
+    managedHooksDir?: string;
+    bundledHooksDir?: string;
+    entries?: HookEntry[];
+    eligibility?: HookEligibilityContext;
+    snapshotVersion?: number;
+  },
+): HookSnapshot {
+  const hookEntries = opts?.entries ?? loadHookEntries(workspaceDir, opts);
+  const eligible = filterHookEntries(hookEntries, opts?.config, opts?.eligibility);
+
+  return {
+    hooks: eligible.map((entry) => ({
+      name: entry.hook.name,
+      events: entry.clawdbot?.events ?? [],
+    })),
+    resolvedHooks: eligible.map((entry) => entry.hook),
+    version: opts?.snapshotVersion,
+  };
+}
+
+export function loadWorkspaceHookEntries(
+  workspaceDir: string,
+  opts?: {
+    config?: ClawdbotConfig;
+    managedHooksDir?: string;
+    bundledHooksDir?: string;
+  },
+): HookEntry[] {
+  return loadHookEntries(workspaceDir, opts);
+}