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/auto-reply/reply/commands-core.ts
+++ b/src/auto-reply/reply/commands-core.ts
@@ -1,6 +1,8 @@
 import { logVerbose } from "../../globals.js";
 import { resolveSendPolicy } from "../../sessions/send-policy.js";
 import { shouldHandleTextCommands } from "../commands-registry.js";
+import { createInternalHookEvent, triggerInternalHook } from "../../hooks/internal-hooks.js";
+import { routeReply } from "./route-reply.js";
 import { handleBashCommand } from "./commands-bash.js";
 import { handleCompactCommand } from "./commands-compact.js";
 import { handleConfigCommand, handleDebugCommand } from "./commands-config.js";
@@ -42,9 +44,8 @@ const HANDLERS: CommandHandler[] = [
 ];

 export async function handleCommands(params: HandleCommandsParams): Promise<CommandHandlerResult> {
-  const resetRequested =
-    params.command.commandBodyNormalized === "/reset" ||
-    params.command.commandBodyNormalized === "/new";
+  const resetMatch = params.command.commandBodyNormalized.match(/^\/(new|reset)(?:\s|$)/);
+  const resetRequested = Boolean(resetMatch);
  if (resetRequested && !params.command.isAuthorizedSender) {
    logVerbose(
      `Ignoring /reset from unauthorized sender: ${params.command.senderId || "<unknown>"}`,
@@ -52,6 +53,45 @@ export async function handleCommands(params: HandleCommandsParams): Promise<Comm
    return { shouldContinue: false };
  }

+  // Trigger internal hook for reset/new commands
+  if (resetRequested && params.command.isAuthorizedSender) {
+    const commandAction = resetMatch?.[1] ?? "new";
+    const hookEvent = createInternalHookEvent(
+      'command',
+      commandAction,
+      params.sessionKey ?? '',
+      {
+        sessionEntry: params.sessionEntry,
+        previousSessionEntry: params.previousSessionEntry,
+        commandSource: params.command.surface,
+        senderId: params.command.senderId,
+        cfg: params.cfg, // Pass config for LLM slug generation
+      }
+    );
+    await triggerInternalHook(hookEvent);
+
+    // Send hook messages immediately if present
+    if (hookEvent.messages.length > 0) {
+      // Use OriginatingChannel/To if available, otherwise fall back to command channel/from
+      const channel = params.ctx.OriginatingChannel || (params.command.channel as any);
+      // For replies, use 'from' (the sender) not 'to' (which might be the bot itself)
+      const to = params.ctx.OriginatingTo || params.command.from || params.command.to;
+
+      if (channel && to) {
+        const hookReply = { text: hookEvent.messages.join('\n\n') };
+        await routeReply({
+          payload: hookReply,
+          channel: channel,
+          to: to,
+          sessionKey: params.sessionKey,
+          accountId: params.ctx.AccountId,
+          threadId: params.ctx.MessageThreadId,
+          cfg: params.cfg,
+        });
+      }
+    }
+  }
+
  const allowTextCommands = shouldHandleTextCommands({
    cfg: params.cfg,
    surface: params.command.surface,
--- a/src/auto-reply/reply/commands-session.ts
+++ b/src/auto-reply/reply/commands-session.ts
@@ -2,6 +2,7 @@ import { abortEmbeddedPiRun } from "../../agents/pi-embedded.js";
 import type { SessionEntry } from "../../config/sessions.js";
 import { updateSessionStore } from "../../config/sessions.js";
 import { logVerbose } from "../../globals.js";
+import { createInternalHookEvent, triggerInternalHook } from "../../hooks/internal-hooks.js";
 import { scheduleGatewaySigusr1Restart, triggerClawdbotRestart } from "../../infra/restart.js";
 import { parseAgentSessionKey } from "../../routing/session-key.js";
 import { parseActivationCommand } from "../group-activation.js";
@@ -12,8 +13,8 @@ import {
  setAbortMemory,
  stopSubagentsForRequester,
 } from "./abort.js";
-import { clearSessionQueues } from "./queue.js";
 import type { CommandHandler } from "./commands-types.js";
+import { clearSessionQueues } from "./queue.js";

 function resolveSessionEntryForKey(
  store: Record<string, SessionEntry> | undefined,
@@ -213,14 +214,27 @@ export const handleStopCommand: CommandHandler = async (params, allowTextCommand
  } else if (params.command.abortKey) {
    setAbortMemory(params.command.abortKey, true);
  }
+
+  // Trigger internal hook for stop command
+  const hookEvent = createInternalHookEvent(
+    'command',
+    'stop',
+    abortTarget.key ?? params.sessionKey ?? '',
+    {
+      sessionEntry: abortTarget.entry ?? params.sessionEntry,
+      sessionId: abortTarget.sessionId,
+      commandSource: params.command.surface,
+      senderId: params.command.senderId,
+    }
+  );
+  await triggerInternalHook(hookEvent);
+
  const { stopped } = stopSubagentsForRequester({
    cfg: params.cfg,
    requesterSessionKey: abortTarget.key ?? params.sessionKey,
  });
-  return {
-    shouldContinue: false,
-    reply: { text: formatAbortReplyText(stopped) },
-  };
+
+  return { shouldContinue: false, reply: { text: formatAbortReplyText(stopped) } };
 };

 export const handleAbortTrigger: CommandHandler = async (params, allowTextCommands) => {
@@ -235,12 +249,6 @@ export const handleAbortTrigger: CommandHandler = async (params, allowTextComman
  if (abortTarget.sessionId) {
    abortEmbeddedPiRun(abortTarget.sessionId);
  }
-  const cleared = clearSessionQueues([abortTarget.key, abortTarget.sessionId]);
-  if (cleared.followupCleared > 0 || cleared.laneCleared > 0) {
-    logVerbose(
-      `stop-trigger: cleared followups=${cleared.followupCleared} lane=${cleared.laneCleared} keys=${cleared.keys.join(",")}`,
-    );
-  }
  if (abortTarget.entry && params.sessionStore && abortTarget.key) {
    abortTarget.entry.abortedLastRun = true;
    abortTarget.entry.updatedAt = Date.now();
@@ -253,12 +261,5 @@ export const handleAbortTrigger: CommandHandler = async (params, allowTextComman
  } else if (params.command.abortKey) {
    setAbortMemory(params.command.abortKey, true);
  }
-  const { stopped } = stopSubagentsForRequester({
-    cfg: params.cfg,
-    requesterSessionKey: abortTarget.key ?? params.sessionKey,
-  });
-  return {
-    shouldContinue: false,
-    reply: { text: formatAbortReplyText(stopped) },
-  };
+  return { shouldContinue: false, reply: { text: "⚙️ Agent was aborted." } };
 };
--- a/src/auto-reply/reply/commands-types.ts
+++ b/src/auto-reply/reply/commands-types.ts
@@ -33,6 +33,7 @@ export type HandleCommandsParams = {
    failures: Array<{ gate: string; key: string }>;
  };
  sessionEntry?: SessionEntry;
+  previousSessionEntry?: SessionEntry;
  sessionStore?: Record<string, SessionEntry>;
  sessionKey: string;
  storePath?: string;
--- a/src/auto-reply/reply/commands.test.ts
+++ b/src/auto-reply/reply/commands.test.ts
@@ -1,6 +1,7 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";

 import type { ClawdbotConfig } from "../../config/config.js";
+import * as internalHooks from "../../hooks/internal-hooks.js";
 import type { MsgContext } from "../templating.js";
 import { resetBashChatCommandForTests } from "./bash-command.js";
 import { buildCommandContext, handleCommands } from "./commands.js";
@@ -143,6 +144,24 @@ describe("handleCommands identity", () => {
  });
 });

+describe("handleCommands internal hooks", () => {
+  it("triggers hooks for /new with arguments", async () => {
+    const cfg = {
+      commands: { text: true },
+      channels: { whatsapp: { allowFrom: ["*"] } },
+    } as ClawdbotConfig;
+    const params = buildParams("/new take notes", cfg);
+    const spy = vi.spyOn(internalHooks, "triggerInternalHook").mockResolvedValue();
+
+    await handleCommands(params);
+
+    expect(spy).toHaveBeenCalledWith(
+      expect.objectContaining({ type: "command", action: "new" }),
+    );
+    spy.mockRestore();
+  });
+});
+
 describe("handleCommands context", () => {
  it("returns context help for /context", async () => {
    const cfg = {
--- a/src/auto-reply/reply/get-reply-inline-actions.ts
+++ b/src/auto-reply/reply/get-reply-inline-actions.ts
@@ -29,6 +29,7 @@ export async function handleInlineActions(params: {
  cfg: ClawdbotConfig;
  agentId: string;
  sessionEntry?: SessionEntry;
+  previousSessionEntry?: SessionEntry;
  sessionStore?: Record<string, SessionEntry>;
  sessionKey: string;
  storePath?: string;
@@ -66,8 +67,9 @@ export async function handleInlineActions(params: {
    sessionCtx,
    cfg,
    agentId,
-    sessionEntry,
-    sessionStore,
+  sessionEntry,
+  previousSessionEntry,
+  sessionStore,
    sessionKey,
    storePath,
    sessionScope,
@@ -203,6 +205,7 @@ export async function handleInlineActions(params: {
        failures: elevatedFailures,
      },
      sessionEntry,
+      previousSessionEntry,
      sessionStore,
      sessionKey,
      storePath,
@@ -265,6 +268,7 @@ export async function handleInlineActions(params: {
      failures: elevatedFailures,
    },
    sessionEntry,
+    previousSessionEntry,
    sessionStore,
    sessionKey,
    storePath,
--- a/src/auto-reply/reply/get-reply.ts
+++ b/src/auto-reply/reply/get-reply.ts
@@ -100,6 +100,7 @@ export async function getReplyFromConfig(
  let {
    sessionCtx,
    sessionEntry,
+    previousSessionEntry,
    sessionStore,
    sessionKey,
    sessionId,
@@ -122,6 +123,7 @@ export async function getReplyFromConfig(
    agentCfg,
    sessionCtx,
    sessionEntry,
+    previousSessionEntry,
    sessionStore,
    sessionKey,
    storePath,
--- a/src/auto-reply/reply/session.ts
+++ b/src/auto-reply/reply/session.ts
@@ -30,6 +30,7 @@ import { stripMentions, stripStructuralPrefixes } from "./mentions.js";
 export type SessionInitResult = {
  sessionCtx: TemplateContext;
  sessionEntry: SessionEntry;
+  previousSessionEntry?: SessionEntry;
  sessionStore: Record<string, SessionEntry>;
  sessionKey: string;
  sessionId: string;
@@ -115,6 +116,7 @@ export async function initSessionState(params: {
  let bodyStripped: string | undefined;
  let systemSent = false;
  let abortedLastRun = false;
+  let resetTriggered = false;

  let persistedThinking: string | undefined;
  let persistedVerbose: string | undefined;
@@ -149,12 +151,14 @@ export async function initSessionState(params: {
    if (trimmedBody === trigger || strippedForReset === trigger) {
      isNewSession = true;
      bodyStripped = "";
+      resetTriggered = true;
      break;
    }
    const triggerPrefix = `${trigger} `;
    if (trimmedBody.startsWith(triggerPrefix) || strippedForReset.startsWith(triggerPrefix)) {
      isNewSession = true;
      bodyStripped = strippedForReset.slice(trigger.length).trimStart();
+      resetTriggered = true;
      break;
    }
  }
@@ -168,6 +172,7 @@ export async function initSessionState(params: {
    }
  }
  const entry = sessionStore[sessionKey];
+  const previousSessionEntry = resetTriggered && entry ? { ...entry } : undefined;
  const idleMs = idleMinutes * 60_000;
  const freshEntry = entry && Date.now() - entry.updatedAt <= idleMs;

@@ -308,6 +313,7 @@ export async function initSessionState(params: {
  return {
    sessionCtx,
    sessionEntry,
+    previousSessionEntry,
    sessionStore,
    sessionKey,
    sessionId: sessionId ?? crypto.randomUUID(),
--- a/src/auto-reply/templating.ts
+++ b/src/auto-reply/templating.ts
@@ -75,6 +75,11 @@ export type MsgContext = {
   * The chat/channel/user ID where the reply should be sent.
   */
  OriginatingTo?: string;
+  /**
+   * Messages from internal hooks to be included in the response.
+   * Used for hook confirmation messages like "Session context saved to memory".
+   */
+  HookMessages?: string[];
 };

 export type TemplateContext = MsgContext & {
--- a/src/cli/hooks-cli.ts
+++ b/src/cli/hooks-cli.ts
@@ -20,6 +20,7 @@ import {
 import { defaultRuntime } from "../runtime.js";
 import { formatDocsLink } from "../terminal/links.js";
 import { theme } from "../terminal/theme.js";
+import { registerInternalHooksSubcommands } from "./hooks-internal-cli.js";

 export function registerHooksCli(program: Command) {
  const hooks = program
@@ -31,6 +32,9 @@ export function registerHooksCli(program: Command) {
        `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/hooks", "docs.clawd.bot/cli/hooks")}\n`,
    );

+  // Register internal hooks management subcommands
+  registerInternalHooksSubcommands(hooks);
+
  const gmail = hooks.command("gmail").description("Gmail Pub/Sub hooks (via gogcli)");

  gmail
--- a/src/cli/hooks-internal-cli.ts
+++ b/src/cli/hooks-internal-cli.ts
@@ -0,0 +1,439 @@
+import chalk from "chalk";
+import type { Command } from "commander";
+import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agents/agent-scope.js";
+import {
+  buildWorkspaceHookStatus,
+  type HookStatusEntry,
+  type HookStatusReport,
+} from "../hooks/hooks-status.js";
+import { loadConfig, writeConfigFile } from "../config/io.js";
+
+export type HooksListOptions = {
+  json?: boolean;
+  eligible?: boolean;
+  verbose?: boolean;
+};
+
+export type HookInfoOptions = {
+  json?: boolean;
+};
+
+export type HooksCheckOptions = {
+  json?: boolean;
+};
+
+/**
+ * Format a single hook for display in the list
+ */
+function formatHookLine(hook: HookStatusEntry, verbose = false): string {
+  const emoji = hook.emoji ?? "🔗";
+  const status = hook.eligible
+    ? chalk.green("✓")
+    : hook.disabled
+      ? chalk.yellow("disabled")
+      : chalk.red("missing reqs");
+
+  const name = hook.eligible ? chalk.white(hook.name) : chalk.gray(hook.name);
+
+  const desc = chalk.gray(
+    hook.description.length > 50 ? `${hook.description.slice(0, 47)}...` : hook.description,
+  );
+
+  if (verbose) {
+    const missing: string[] = [];
+    if (hook.missing.bins.length > 0) {
+      missing.push(`bins: ${hook.missing.bins.join(", ")}`);
+    }
+    if (hook.missing.anyBins.length > 0) {
+      missing.push(`anyBins: ${hook.missing.anyBins.join(", ")}`);
+    }
+    if (hook.missing.env.length > 0) {
+      missing.push(`env: ${hook.missing.env.join(", ")}`);
+    }
+    if (hook.missing.config.length > 0) {
+      missing.push(`config: ${hook.missing.config.join(", ")}`);
+    }
+    if (hook.missing.os.length > 0) {
+      missing.push(`os: ${hook.missing.os.join(", ")}`);
+    }
+    const missingStr = missing.length > 0 ? chalk.red(` [${missing.join("; ")}]`) : "";
+    return `${emoji} ${name} ${status}${missingStr}\n   ${desc}`;
+  }
+
+  return `${emoji} ${name} ${status} - ${desc}`;
+}
+
+/**
+ * Format the hooks list output
+ */
+export function formatHooksList(report: HookStatusReport, opts: HooksListOptions): string {
+  const hooks = opts.eligible ? report.hooks.filter((h) => h.eligible) : report.hooks;
+
+  if (opts.json) {
+    const jsonReport = {
+      workspaceDir: report.workspaceDir,
+      managedHooksDir: report.managedHooksDir,
+      hooks: hooks.map((h) => ({
+        name: h.name,
+        description: h.description,
+        emoji: h.emoji,
+        eligible: h.eligible,
+        disabled: h.disabled,
+        source: h.source,
+        events: h.events,
+        homepage: h.homepage,
+        missing: h.missing,
+      })),
+    };
+    return JSON.stringify(jsonReport, null, 2);
+  }
+
+  if (hooks.length === 0) {
+    const message = opts.eligible
+      ? "No eligible hooks found. Run `clawdbot hooks list` to see all hooks."
+      : "No hooks found.";
+    return message;
+  }
+
+  const eligible = hooks.filter((h) => h.eligible);
+  const notEligible = hooks.filter((h) => !h.eligible);
+
+  const lines: string[] = [];
+  lines.push(
+    chalk.bold.cyan("Internal Hooks") + chalk.gray(` (${eligible.length}/${hooks.length} ready)`),
+  );
+  lines.push("");
+
+  if (eligible.length > 0) {
+    lines.push(chalk.bold.green("Ready:"));
+    for (const hook of eligible) {
+      lines.push(`  ${formatHookLine(hook, opts.verbose)}`);
+    }
+  }
+
+  if (notEligible.length > 0 && !opts.eligible) {
+    if (eligible.length > 0) lines.push("");
+    lines.push(chalk.bold.yellow("Not ready:"));
+    for (const hook of notEligible) {
+      lines.push(`  ${formatHookLine(hook, opts.verbose)}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format detailed info for a single hook
+ */
+export function formatHookInfo(
+  report: HookStatusReport,
+  hookName: string,
+  opts: HookInfoOptions,
+): string {
+  const hook = report.hooks.find((h) => h.name === hookName || h.hookKey === hookName);
+
+  if (!hook) {
+    if (opts.json) {
+      return JSON.stringify({ error: "not found", hook: hookName }, null, 2);
+    }
+    return `Hook "${hookName}" not found. Run \`clawdbot hooks list\` to see available hooks.`;
+  }
+
+  if (opts.json) {
+    return JSON.stringify(hook, null, 2);
+  }
+
+  const lines: string[] = [];
+  const emoji = hook.emoji ?? "🔗";
+  const status = hook.eligible
+    ? chalk.green("✓ Ready")
+    : hook.disabled
+      ? chalk.yellow("⏸ Disabled")
+      : chalk.red("✗ Missing requirements");
+
+  lines.push(`${emoji} ${chalk.bold.cyan(hook.name)} ${status}`);
+  lines.push("");
+  lines.push(chalk.white(hook.description));
+  lines.push("");
+
+  // Details
+  lines.push(chalk.bold("Details:"));
+  lines.push(`  Source: ${hook.source}`);
+  lines.push(`  Path: ${chalk.gray(hook.filePath)}`);
+  lines.push(`  Handler: ${chalk.gray(hook.handlerPath)}`);
+  if (hook.homepage) {
+    lines.push(`  Homepage: ${chalk.blue(hook.homepage)}`);
+  }
+  if (hook.events.length > 0) {
+    lines.push(`  Events: ${hook.events.join(", ")}`);
+  }
+
+  // Requirements
+  const hasRequirements =
+    hook.requirements.bins.length > 0 ||
+    hook.requirements.anyBins.length > 0 ||
+    hook.requirements.env.length > 0 ||
+    hook.requirements.config.length > 0 ||
+    hook.requirements.os.length > 0;
+
+  if (hasRequirements) {
+    lines.push("");
+    lines.push(chalk.bold("Requirements:"));
+    if (hook.requirements.bins.length > 0) {
+      const binsStatus = hook.requirements.bins.map((bin) => {
+        const missing = hook.missing.bins.includes(bin);
+        return missing ? chalk.red(`✗ ${bin}`) : chalk.green(`✓ ${bin}`);
+      });
+      lines.push(`  Binaries: ${binsStatus.join(", ")}`);
+    }
+    if (hook.requirements.anyBins.length > 0) {
+      const anyBinsStatus =
+        hook.missing.anyBins.length > 0
+          ? chalk.red(`✗ (any of: ${hook.requirements.anyBins.join(", ")})`)
+          : chalk.green(`✓ (any of: ${hook.requirements.anyBins.join(", ")})`);
+      lines.push(`  Any binary: ${anyBinsStatus}`);
+    }
+    if (hook.requirements.env.length > 0) {
+      const envStatus = hook.requirements.env.map((env) => {
+        const missing = hook.missing.env.includes(env);
+        return missing ? chalk.red(`✗ ${env}`) : chalk.green(`✓ ${env}`);
+      });
+      lines.push(`  Environment: ${envStatus.join(", ")}`);
+    }
+    if (hook.requirements.config.length > 0) {
+      const configStatus = hook.configChecks.map((check) => {
+        return check.satisfied
+          ? chalk.green(`✓ ${check.path}`)
+          : chalk.red(`✗ ${check.path}`);
+      });
+      lines.push(`  Config: ${configStatus.join(", ")}`);
+    }
+    if (hook.requirements.os.length > 0) {
+      const osStatus =
+        hook.missing.os.length > 0
+          ? chalk.red(`✗ (${hook.requirements.os.join(", ")})`)
+          : chalk.green(`✓ (${hook.requirements.os.join(", ")})`);
+      lines.push(`  OS: ${osStatus}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format check output
+ */
+export function formatHooksCheck(report: HookStatusReport, opts: HooksCheckOptions): string {
+  if (opts.json) {
+    const eligible = report.hooks.filter((h) => h.eligible);
+    const notEligible = report.hooks.filter((h) => !h.eligible);
+    return JSON.stringify(
+      {
+        total: report.hooks.length,
+        eligible: eligible.length,
+        notEligible: notEligible.length,
+        hooks: {
+          eligible: eligible.map((h) => h.name),
+          notEligible: notEligible.map((h) => ({
+            name: h.name,
+            missing: h.missing,
+          })),
+        },
+      },
+      null,
+      2,
+    );
+  }
+
+  const eligible = report.hooks.filter((h) => h.eligible);
+  const notEligible = report.hooks.filter((h) => !h.eligible);
+
+  const lines: string[] = [];
+  lines.push(chalk.bold.cyan("Internal Hooks Status"));
+  lines.push("");
+  lines.push(`Total hooks: ${report.hooks.length}`);
+  lines.push(chalk.green(`Ready: ${eligible.length}`));
+  lines.push(chalk.yellow(`Not ready: ${notEligible.length}`));
+
+  if (notEligible.length > 0) {
+    lines.push("");
+    lines.push(chalk.bold.yellow("Hooks not ready:"));
+    for (const hook of notEligible) {
+      const reasons = [];
+      if (hook.disabled) reasons.push("disabled");
+      if (hook.missing.bins.length > 0) reasons.push(`bins: ${hook.missing.bins.join(", ")}`);
+      if (hook.missing.anyBins.length > 0)
+        reasons.push(`anyBins: ${hook.missing.anyBins.join(", ")}`);
+      if (hook.missing.env.length > 0) reasons.push(`env: ${hook.missing.env.join(", ")}`);
+      if (hook.missing.config.length > 0)
+        reasons.push(`config: ${hook.missing.config.join(", ")}`);
+      if (hook.missing.os.length > 0) reasons.push(`os: ${hook.missing.os.join(", ")}`);
+      lines.push(`  ${hook.emoji ?? "🔗"} ${hook.name} - ${reasons.join("; ")}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+export async function enableHook(hookName: string): Promise<void> {
+  const config = loadConfig();
+  const workspaceDir = resolveAgentWorkspaceDir(config, resolveDefaultAgentId(config));
+  const report = buildWorkspaceHookStatus(workspaceDir, { config });
+  const hook = report.hooks.find((h) => h.name === hookName);
+
+  if (!hook) {
+    throw new Error(`Hook "${hookName}" not found`);
+  }
+
+  if (!hook.eligible) {
+    throw new Error(`Hook "${hookName}" is not eligible (missing requirements)`);
+  }
+
+  // Update config
+  const entries = { ...config.hooks?.internal?.entries };
+  entries[hookName] = { ...entries[hookName], enabled: true };
+
+  const nextConfig = {
+    ...config,
+    hooks: {
+      ...config.hooks,
+      internal: {
+        ...config.hooks?.internal,
+        enabled: true,
+        entries,
+      },
+    },
+  };
+
+  await writeConfigFile(nextConfig);
+  console.log(`${chalk.green("✓")} Enabled hook: ${hook.emoji ?? "🔗"} ${hookName}`);
+}
+
+export async function disableHook(hookName: string): Promise<void> {
+  const config = loadConfig();
+  const workspaceDir = resolveAgentWorkspaceDir(config, resolveDefaultAgentId(config));
+  const report = buildWorkspaceHookStatus(workspaceDir, { config });
+  const hook = report.hooks.find((h) => h.name === hookName);
+
+  if (!hook) {
+    throw new Error(`Hook "${hookName}" not found`);
+  }
+
+  // Update config
+  const entries = { ...config.hooks?.internal?.entries };
+  entries[hookName] = { ...entries[hookName], enabled: false };
+
+  const nextConfig = {
+    ...config,
+    hooks: {
+      ...config.hooks,
+      internal: {
+        ...config.hooks?.internal,
+        entries,
+      },
+    },
+  };
+
+  await writeConfigFile(nextConfig);
+  console.log(`${chalk.yellow("⏸")} Disabled hook: ${hook.emoji ?? "🔗"} ${hookName}`);
+}
+
+export function registerInternalHooksSubcommands(hooksCommand: Command): void {
+  // Add "internal" subcommand to existing "hooks" command
+  const internal = hooksCommand
+    .command("internal")
+    .description("Manage internal agent hooks")
+    .alias("int");
+
+  // list command
+  internal
+    .command("list")
+    .description("List all internal hooks")
+    .option("--eligible", "Show only eligible hooks", false)
+    .option("--json", "Output as JSON", false)
+    .option("-v, --verbose", "Show more details including missing requirements", false)
+    .action(async (opts) => {
+      try {
+        const config = loadConfig();
+        const workspaceDir = resolveAgentWorkspaceDir(config, resolveDefaultAgentId(config));
+        const report = buildWorkspaceHookStatus(workspaceDir, { config });
+        console.log(formatHooksList(report, opts));
+      } catch (err) {
+        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
+    });
+
+  // info command
+  internal
+    .command("info <name>")
+    .description("Show detailed information about a hook")
+    .option("--json", "Output as JSON", false)
+    .action(async (name, opts) => {
+      try {
+        const config = loadConfig();
+        const workspaceDir = resolveAgentWorkspaceDir(config, resolveDefaultAgentId(config));
+        const report = buildWorkspaceHookStatus(workspaceDir, { config });
+        console.log(formatHookInfo(report, name, opts));
+      } catch (err) {
+        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
+    });
+
+  // check command
+  internal
+    .command("check")
+    .description("Check hooks eligibility status")
+    .option("--json", "Output as JSON", false)
+    .action(async (opts) => {
+      try {
+        const config = loadConfig();
+        const workspaceDir = resolveAgentWorkspaceDir(config, resolveDefaultAgentId(config));
+        const report = buildWorkspaceHookStatus(workspaceDir, { config });
+        console.log(formatHooksCheck(report, opts));
+      } catch (err) {
+        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
+    });
+
+  // enable command
+  internal
+    .command("enable <name>")
+    .description("Enable a hook")
+    .action(async (name) => {
+      try {
+        await enableHook(name);
+      } catch (err) {
+        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
+    });
+
+  // disable command
+  internal
+    .command("disable <name>")
+    .description("Disable a hook")
+    .action(async (name) => {
+      try {
+        await disableHook(name);
+      } catch (err) {
+        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
+    });
+
+  // Default action (no subcommand) - show list
+  internal.action(async () => {
+    try {
+      const config = loadConfig();
+      const workspaceDir = resolveAgentWorkspaceDir(config, resolveDefaultAgentId(config));
+      const report = buildWorkspaceHookStatus(workspaceDir, { config });
+      console.log(formatHooksList(report, {}));
+    } catch (err) {
+      console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  });
+}
--- a/src/commands/onboard-hooks.test.ts
+++ b/src/commands/onboard-hooks.test.ts
@@ -0,0 +1,185 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+import { setupInternalHooks } from './onboard-hooks.js';
+import type { ClawdbotConfig } from '../config/config.js';
+import type { RuntimeEnv } from '../runtime.js';
+import type { WizardPrompter } from '../wizard/prompts.js';
+import type { HookStatusReport } from '../hooks/hooks-status.js';
+
+// Mock hook discovery modules
+vi.mock('../hooks/hooks-status.js', () => ({
+  buildWorkspaceHookStatus: vi.fn(),
+}));
+
+vi.mock('../agents/agent-scope.js', () => ({
+  resolveAgentWorkspaceDir: vi.fn().mockReturnValue('/mock/workspace'),
+  resolveDefaultAgentId: vi.fn().mockReturnValue('main'),
+}));
+
+describe('onboard-hooks', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  const createMockPrompter = (multiselectValue: string[]): WizardPrompter => ({
+    confirm: vi.fn().mockResolvedValue(true),
+    note: vi.fn().mockResolvedValue(undefined),
+    intro: vi.fn().mockResolvedValue(undefined),
+    outro: vi.fn().mockResolvedValue(undefined),
+    text: vi.fn().mockResolvedValue(''),
+    select: vi.fn().mockResolvedValue(''),
+    multiselect: vi.fn().mockResolvedValue(multiselectValue),
+    progress: vi.fn().mockReturnValue({
+      stop: vi.fn(),
+      update: vi.fn(),
+    }),
+  });
+
+  const createMockRuntime = (): RuntimeEnv => ({
+    log: vi.fn(),
+    error: vi.fn(),
+    exit: vi.fn(),
+  });
+
+  const createMockHookReport = (eligible = true): HookStatusReport => ({
+    workspaceDir: '/mock/workspace',
+    managedHooksDir: '/mock/.clawdbot/hooks',
+    hooks: [
+      {
+        name: 'session-memory',
+        description: 'Save session context to memory when /new command is issued',
+        source: 'clawdbot-bundled',
+        emoji: '💾',
+        events: ['command:new'],
+        disabled: false,
+        eligible,
+        requirements: { config: ['workspace.dir'] },
+        missing: {},
+      },
+    ],
+  });
+
+  describe('setupInternalHooks', () => {
+    it('should enable internal hooks when user selects them', async () => {
+      const { buildWorkspaceHookStatus } = await import('../hooks/hooks-status.js');
+      vi.mocked(buildWorkspaceHookStatus).mockReturnValue(createMockHookReport());
+
+      const cfg: ClawdbotConfig = {};
+      const prompter = createMockPrompter(['session-memory']);
+      const runtime = createMockRuntime();
+
+      const result = await setupInternalHooks(cfg, runtime, prompter);
+
+      expect(result.hooks?.internal?.enabled).toBe(true);
+      expect(result.hooks?.internal?.entries).toEqual({
+        'session-memory': { enabled: true },
+      });
+      expect(prompter.note).toHaveBeenCalledTimes(2);
+      expect(prompter.multiselect).toHaveBeenCalledWith({
+        message: 'Enable internal hooks?',
+        options: [
+          { value: '__skip__', label: 'Skip for now' },
+          {
+            value: 'session-memory',
+            label: '💾 session-memory',
+            hint: 'Save session context to memory when /new command is issued',
+          },
+        ],
+      });
+    });
+
+    it('should not enable hooks when user skips', async () => {
+      const { buildWorkspaceHookStatus } = await import('../hooks/hooks-status.js');
+      vi.mocked(buildWorkspaceHookStatus).mockReturnValue(createMockHookReport());
+
+      const cfg: ClawdbotConfig = {};
+      const prompter = createMockPrompter(['__skip__']);
+      const runtime = createMockRuntime();
+
+      const result = await setupInternalHooks(cfg, runtime, prompter);
+
+      expect(result.hooks?.internal).toBeUndefined();
+      expect(prompter.note).toHaveBeenCalledTimes(1);
+    });
+
+    it('should handle no eligible hooks', async () => {
+      const { buildWorkspaceHookStatus } = await import('../hooks/hooks-status.js');
+      vi.mocked(buildWorkspaceHookStatus).mockReturnValue(createMockHookReport(false));
+
+      const cfg: ClawdbotConfig = {};
+      const prompter = createMockPrompter([]);
+      const runtime = createMockRuntime();
+
+      const result = await setupInternalHooks(cfg, runtime, prompter);
+
+      expect(result).toEqual(cfg);
+      expect(prompter.multiselect).not.toHaveBeenCalled();
+      expect(prompter.note).toHaveBeenCalledWith(
+        'No eligible hooks found. You can configure hooks later in your config.',
+        'No Hooks Available',
+      );
+    });
+
+    it('should preserve existing hooks config when enabled', async () => {
+      const { buildWorkspaceHookStatus } = await import('../hooks/hooks-status.js');
+      vi.mocked(buildWorkspaceHookStatus).mockReturnValue(createMockHookReport());
+
+      const cfg: ClawdbotConfig = {
+        hooks: {
+          enabled: true,
+          path: '/webhook',
+          token: 'existing-token',
+        },
+      };
+      const prompter = createMockPrompter(['session-memory']);
+      const runtime = createMockRuntime();
+
+      const result = await setupInternalHooks(cfg, runtime, prompter);
+
+      expect(result.hooks?.enabled).toBe(true);
+      expect(result.hooks?.path).toBe('/webhook');
+      expect(result.hooks?.token).toBe('existing-token');
+      expect(result.hooks?.internal?.enabled).toBe(true);
+      expect(result.hooks?.internal?.entries).toEqual({
+        'session-memory': { enabled: true },
+      });
+    });
+
+    it('should preserve existing config when user skips', async () => {
+      const { buildWorkspaceHookStatus } = await import('../hooks/hooks-status.js');
+      vi.mocked(buildWorkspaceHookStatus).mockReturnValue(createMockHookReport());
+
+      const cfg: ClawdbotConfig = {
+        agents: { defaults: { workspace: '/workspace' } },
+      };
+      const prompter = createMockPrompter(['__skip__']);
+      const runtime = createMockRuntime();
+
+      const result = await setupInternalHooks(cfg, runtime, prompter);
+
+      expect(result).toEqual(cfg);
+      expect(result.agents?.defaults?.workspace).toBe('/workspace');
+    });
+
+    it('should show informative notes to user', async () => {
+      const { buildWorkspaceHookStatus } = await import('../hooks/hooks-status.js');
+      vi.mocked(buildWorkspaceHookStatus).mockReturnValue(createMockHookReport());
+
+      const cfg: ClawdbotConfig = {};
+      const prompter = createMockPrompter(['session-memory']);
+      const runtime = createMockRuntime();
+
+      await setupInternalHooks(cfg, runtime, prompter);
+
+      const noteCalls = (prompter.note as ReturnType<typeof vi.fn>).mock.calls;
+      expect(noteCalls).toHaveLength(2);
+
+      // First note should explain what internal hooks are
+      expect(noteCalls[0][0]).toContain('Internal hooks');
+      expect(noteCalls[0][0]).toContain('automate actions');
+
+      // Second note should confirm configuration
+      expect(noteCalls[1][0]).toContain('Enabled 1 hook: session-memory');
+      expect(noteCalls[1][0]).toContain('clawdbot hooks internal list');
+    });
+  });
+});
--- a/src/commands/onboard-hooks.ts
+++ b/src/commands/onboard-hooks.ts
@@ -0,0 +1,86 @@
+import type { ClawdbotConfig } from "../config/config.js";
+import type { RuntimeEnv } from "../runtime.js";
+import type { WizardPrompter } from "../wizard/prompts.js";
+import { buildWorkspaceHookStatus } from "../hooks/hooks-status.js";
+import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agents/agent-scope.js";
+
+export async function setupInternalHooks(
+  cfg: ClawdbotConfig,
+  runtime: RuntimeEnv,
+  prompter: WizardPrompter,
+): Promise<ClawdbotConfig> {
+  await prompter.note(
+    [
+      "Internal hooks let you automate actions when agent commands are issued.",
+      "Example: Save session context to memory when you issue /new.",
+      "",
+      "Learn more: https://docs.clawd.bot/internal-hooks",
+    ].join("\n"),
+    "Internal Hooks",
+  );
+
+  // Discover available hooks using the hook discovery system
+  const workspaceDir = resolveAgentWorkspaceDir(cfg, resolveDefaultAgentId(cfg));
+  const report = buildWorkspaceHookStatus(workspaceDir, { config: cfg });
+
+  // Filter for eligible and recommended hooks (session-memory is recommended)
+  const recommendedHooks = report.hooks.filter(
+    (h) => h.eligible && h.name === "session-memory",
+  );
+
+  if (recommendedHooks.length === 0) {
+    await prompter.note(
+      "No eligible hooks found. You can configure hooks later in your config.",
+      "No Hooks Available",
+    );
+    return cfg;
+  }
+
+  const toEnable = await prompter.multiselect({
+    message: "Enable internal hooks?",
+    options: [
+      { value: "__skip__", label: "Skip for now" },
+      ...recommendedHooks.map((hook) => ({
+        value: hook.name,
+        label: `${hook.emoji ?? "🔗"} ${hook.name}`,
+        hint: hook.description,
+      })),
+    ],
+  });
+
+  const selected = toEnable.filter((name) => name !== "__skip__");
+  if (selected.length === 0) {
+    return cfg;
+  }
+
+  // Enable selected hooks using the new entries config format
+  const entries = { ...cfg.hooks?.internal?.entries };
+  for (const name of selected) {
+    entries[name] = { enabled: true };
+  }
+
+  const next: ClawdbotConfig = {
+    ...cfg,
+    hooks: {
+      ...cfg.hooks,
+      internal: {
+        enabled: true,
+        entries,
+      },
+    },
+  };
+
+  await prompter.note(
+    [
+      `Enabled ${selected.length} hook${selected.length > 1 ? "s" : ""}: ${selected.join(", ")}`,
+      "",
+      "You can manage hooks later with:",
+      "  clawdbot hooks internal list",
+      "  clawdbot hooks internal enable <name>",
+      "  clawdbot hooks internal disable <name>",
+    ].join("\n"),
+    "Hooks Configured",
+  );
+
+  return next;
+}
--- a/src/config/types.hooks.ts
+++ b/src/config/types.hooks.ts
@@ -64,6 +64,35 @@ export type HooksGmailConfig = {
  thinking?: "off" | "minimal" | "low" | "medium" | "high";
 };

+export type InternalHookHandlerConfig = {
+  /** Event key to listen for (e.g., 'command:new', 'session:start') */
+  event: string;
+  /** Path to handler module (absolute or relative to cwd) */
+  module: string;
+  /** Export name from module (default: 'default') */
+  export?: string;
+};
+
+export type HookConfig = {
+  enabled?: boolean;
+  env?: Record<string, string>;
+  [key: string]: unknown;
+};
+
+export type InternalHooksConfig = {
+  /** Enable internal hooks system */
+  enabled?: boolean;
+  /** Legacy: List of internal hook handlers to register (still supported) */
+  handlers?: InternalHookHandlerConfig[];
+  /** Per-hook configuration overrides */
+  entries?: Record<string, HookConfig>;
+  /** Load configuration */
+  load?: {
+    /** Additional hook directories to scan */
+    extraDirs?: string[];
+  };
+};
+
 export type HooksConfig = {
  enabled?: boolean;
  path?: string;
@@ -73,4 +102,6 @@ export type HooksConfig = {
  transformsDir?: string;
  mappings?: HookMappingConfig[];
  gmail?: HooksGmailConfig;
+  /** Internal agent event hooks */
+  internal?: InternalHooksConfig;
 };
--- a/src/config/zod-schema.hooks.ts
+++ b/src/config/zod-schema.hooks.ts
@@ -41,6 +41,32 @@ export const HookMappingSchema = z
  })
  .optional();

+export const InternalHookHandlerSchema = z.object({
+  event: z.string(),
+  module: z.string(),
+  export: z.string().optional(),
+});
+
+const HookConfigSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    env: z.record(z.string(), z.string()).optional(),
+  })
+  .passthrough();
+
+export const InternalHooksSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    handlers: z.array(InternalHookHandlerSchema).optional(),
+    entries: z.record(z.string(), HookConfigSchema).optional(),
+    load: z
+      .object({
+        extraDirs: z.array(z.string()).optional(),
+      })
+      .optional(),
+  })
+  .optional();
+
 export const HooksGmailSchema = z
  .object({
    account: z.string().optional(),
--- a/src/config/zod-schema.ts
+++ b/src/config/zod-schema.ts
@@ -2,7 +2,7 @@ import { z } from "zod";
 import { ToolsSchema } from "./zod-schema.agent-runtime.js";
 import { AgentsSchema, AudioSchema, BindingsSchema, BroadcastSchema } from "./zod-schema.agents.js";
 import { HexColorSchema, ModelsConfigSchema } from "./zod-schema.core.js";
-import { HookMappingSchema, HooksGmailSchema } from "./zod-schema.hooks.js";
+import { HookMappingSchema, HooksGmailSchema, InternalHooksSchema } from "./zod-schema.hooks.js";
 import { ChannelsSchema } from "./zod-schema.providers.js";
 import { CommandsSchema, MessagesSchema, SessionSchema } from "./zod-schema.session.js";

@@ -148,6 +148,7 @@ export const ClawdbotSchema = z
        transformsDir: z.string().optional(),
        mappings: z.array(HookMappingSchema).optional(),
        gmail: HooksGmailSchema,
+        internal: InternalHooksSchema,
      })
      .optional(),
    web: z
--- a/src/gateway/server-startup.ts
+++ b/src/gateway/server-startup.ts
@@ -8,6 +8,8 @@ import {
 import type { CliDeps } from "../cli/deps.js";
 import type { loadConfig } from "../config/config.js";
 import { startGmailWatcher } from "../hooks/gmail-watcher.js";
+import { clearInternalHooks } from "../hooks/internal-hooks.js";
+import { loadInternalHooks } from "../hooks/loader.js";
 import type { loadClawdbotPlugins } from "../plugins/loader.js";
 import { type PluginServicesHandle, startPluginServices } from "../plugins/services.js";
 import { startBrowserControlServerIfEnabled } from "./server-browser.js";
@@ -90,6 +92,18 @@ export async function startGatewaySidecars(params: {
    }
  }

+  // Load internal hook handlers from configuration and directory discovery.
+  try {
+    // Clear any previously registered hooks to ensure fresh loading
+    clearInternalHooks();
+    const loadedCount = await loadInternalHooks(params.cfg, params.defaultWorkspaceDir);
+    if (loadedCount > 0) {
+      params.logHooks.info(`loaded ${loadedCount} internal hook handler${loadedCount > 1 ? 's' : ''}`);
+    }
+  } catch (err) {
+    params.logHooks.error(`failed to load internal hooks: ${String(err)}`);
+  }
+
  // Launch configured channels so gateway replies via the surface the message came from.
  // Tests can opt out via CLAWDBOT_SKIP_CHANNELS (or legacy CLAWDBOT_SKIP_PROVIDERS).
  const skipChannels =
--- 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);
+}
--- a/src/wizard/onboarding.ts
+++ b/src/wizard/onboarding.ts
@@ -19,6 +19,7 @@ import {
 } from "../commands/onboard-helpers.js";
 import { promptRemoteGatewayConfig } from "../commands/onboard-remote.js";
 import { setupSkills } from "../commands/onboard-skills.js";
+import { setupInternalHooks } from "../commands/onboard-hooks.js";
 import type {
  GatewayAuthChoice,
  OnboardMode,
@@ -403,6 +404,10 @@ export async function runOnboardingWizard(
  } else {
    nextConfig = await setupSkills(nextConfig, workspaceDir, runtime, prompter);
  }
+
+  // Setup internal hooks (session memory on /new)
+  nextConfig = await setupInternalHooks(nextConfig, runtime, prompter);
+
  nextConfig = applyWizardMetadata(nextConfig, { command: "onboard", mode });
  await writeConfigFile(nextConfig);