feat: add internal hooks system

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 .
+```

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;