@hasna/hooks 0.0.3 → 0.0.5

package/bin/index.js

@@ -3519,6 +3519,9 @@ var {
 
 // src/cli/index.tsx
 import chalk2 from "chalk";
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { join as join2 } from "path";
+import { homedir as homedir2 } from "os";
 
 // src/cli/components/App.tsx
 import { useState as useState7 } from "react";
@@ -4524,7 +4527,7 @@ import { join, dirname } from "path";
 import { homedir } from "os";
 import { fileURLToPath } from "url";
 var __dirname2 = dirname(fileURLToPath(import.meta.url));
-var HOOKS_DIR = existsSync(join(__dirname2, "..", "..", "hooks")) ? join(__dirname2, "..", "..", "hooks") : join(__dirname2, "..", "hooks");
+var HOOKS_DIR = existsSync(join(__dirname2, "..", "..", "hooks", "hook-gitguard")) ? join(__dirname2, "..", "..", "hooks") : join(__dirname2, "..", "hooks");
 var SETTINGS_PATH = join(homedir(), ".claude", "settings.json");
 function getHookPath(name) {
   const hookName = name.startsWith("hook-") ? name : `hook-${name}`;
@@ -4572,6 +4575,10 @@ function installHook(name, options = {}) {
     if (!existsSync(destDir)) {
       mkdirSync(destDir, { recursive: true });
     }
+    if (overwrite && existsSync(destPath)) {
+      const { rmSync } = __require("fs");
+      rmSync(destPath, { recursive: true, force: true });
+    }
     cpSync(sourcePath, destPath, { recursive: true });
     registerHookInSettings(shortName);
     updateHooksIndex(destDir);
@@ -5028,36 +5035,72 @@ function App({ initialHooks, overwrite = false }) {
 // src/cli/index.tsx
 import { jsxDEV as jsxDEV8 } from "react/jsx-dev-runtime";
 var program2 = new Command;
-program2.name("hooks").description("Install Claude Code hooks for your project").version("0.0.1");
+program2.name("hooks").description("Install Claude Code hooks for your project").version("0.0.5");
 program2.command("interactive", { isDefault: true }).alias("i").description("Interactive hook browser").action(() => {
   render(/* @__PURE__ */ jsxDEV8(App, {}, undefined, false, undefined, this));
 });
-program2.command("install").alias("add").argument("[hooks...]", "Hooks to install").option("-o, --overwrite", "Overwrite existing hooks", false).description("Install one or more hooks").action((hooks, options) => {
-  if (hooks.length === 0) {
+program2.command("install").alias("add").argument("[hooks...]", "Hooks to install").option("-o, --overwrite", "Overwrite existing hooks", false).option("-a, --all", "Install all available hooks", false).option("-c, --category <category>", "Install all hooks in a category").option("-j, --json", "Output as JSON", false).description("Install one or more hooks").action((hooks, options) => {
+  let toInstall = hooks;
+  if (options.all) {
+    toInstall = HOOKS.map((h) => h.name);
+  } else if (options.category) {
+    const category = CATEGORIES.find((c) => c.toLowerCase() === options.category.toLowerCase());
+    if (!category) {
+      if (options.json) {
+        console.log(JSON.stringify({ error: `Unknown category: ${options.category}`, available: [...CATEGORIES] }));
+      } else {
+        console.log(chalk2.red(`Unknown category: ${options.category}`));
+        console.log(chalk2.dim(`Available: ${CATEGORIES.join(", ")}`));
+      }
+      return;
+    }
+    toInstall = getHooksByCategory(category).map((h) => h.name);
+  }
+  if (toInstall.length === 0) {
     render(/* @__PURE__ */ jsxDEV8(App, {}, undefined, false, undefined, this));
     return;
   }
+  const results = [];
+  for (const name of toInstall) {
+    const result = installHook(name, { overwrite: options.overwrite });
+    results.push(result);
+  }
+  if (options.json) {
+    console.log(JSON.stringify({
+      installed: results.filter((r) => r.success).map((r) => r.hook),
+      failed: results.filter((r) => !r.success).map((r) => ({ hook: r.hook, error: r.error })),
+      total: results.length,
+      success: results.filter((r) => r.success).length
+    }));
+    return;
+  }
   console.log(chalk2.bold(`
 Installing hooks...
 `));
-  for (const name of hooks) {
-    const result = installHook(name, { overwrite: options.overwrite });
+  for (const result of results) {
     if (result.success) {
-      const meta = getHook(name);
-      console.log(chalk2.green(`\u2713 ${name}`));
+      const meta = getHook(result.hook);
+      console.log(chalk2.green(`\u2713 ${result.hook}`));
       if (meta) {
-        console.log(chalk2.dim(`  ${meta.event}${meta.matcher ? ` [${meta.matcher}]` : ""} \u2192 hook-${name}`));
+        console.log(chalk2.dim(`  ${meta.event}${meta.matcher ? ` [${meta.matcher}]` : ""} \u2192 hook-${result.hook}`));
       }
     } else {
-      console.log(chalk2.red(`\u2717 ${name}: ${result.error}`));
+      console.log(chalk2.red(`\u2717 ${result.hook}: ${result.error}`));
     }
   }
   console.log(chalk2.dim(`
 Hooks installed to .hooks/ and registered in ~/.claude/settings.json`));
 });
-program2.command("list").alias("ls").option("-c, --category <category>", "Filter by category").option("-a, --all", "Show all available hooks", false).option("-i, --installed", "Show only installed hooks", false).option("-r, --registered", "Show hooks registered in Claude settings", false).description("List available or installed hooks").action((options) => {
+program2.command("list").alias("ls").option("-c, --category <category>", "Filter by category").option("-a, --all", "Show all available hooks", false).option("-i, --installed", "Show only installed hooks", false).option("-r, --registered", "Show hooks registered in Claude settings", false).option("-j, --json", "Output as JSON", false).description("List available or installed hooks").action((options) => {
   if (options.registered) {
     const registered = getRegisteredHooks();
+    if (options.json) {
+      console.log(JSON.stringify(registered.map((name) => {
+        const meta = getHook(name);
+        return { name, event: meta?.event, description: meta?.description };
+      })));
+      return;
+    }
     if (registered.length === 0) {
       console.log(chalk2.dim("No hooks registered in Claude settings"));
       return;
@@ -5073,6 +5116,13 @@ Registered hooks (${registered.length}):
   }
   if (options.installed) {
     const installed = getInstalledHooks();
+    if (options.json) {
+      console.log(JSON.stringify(installed.map((name) => {
+        const meta = getHook(name);
+        return { name, event: meta?.event, version: meta?.version, description: meta?.description };
+      })));
+      return;
+    }
     if (installed.length === 0) {
       console.log(chalk2.dim("No hooks installed"));
       return;
@@ -5088,11 +5138,19 @@ Installed hooks (${installed.length}):
   if (options.category) {
     const category = CATEGORIES.find((c) => c.toLowerCase() === options.category.toLowerCase());
     if (!category) {
-      console.log(chalk2.red(`Unknown category: ${options.category}`));
-      console.log(chalk2.dim(`Available: ${CATEGORIES.join(", ")}`));
+      if (options.json) {
+        console.log(JSON.stringify({ error: `Unknown category: ${options.category}`, available: [...CATEGORIES] }));
+      } else {
+        console.log(chalk2.red(`Unknown category: ${options.category}`));
+        console.log(chalk2.dim(`Available: ${CATEGORIES.join(", ")}`));
+      }
       return;
     }
     const hooks = getHooksByCategory(category);
+    if (options.json) {
+      console.log(JSON.stringify(hooks));
+      return;
+    }
     console.log(chalk2.bold(`
 ${category} (${hooks.length}):
 `));
@@ -5101,6 +5159,14 @@ ${category} (${hooks.length}):
     }
     return;
   }
+  if (options.json) {
+    const result = {};
+    for (const category of CATEGORIES) {
+      result[category] = getHooksByCategory(category);
+    }
+    console.log(JSON.stringify(result));
+    return;
+  }
   console.log(chalk2.bold(`
 Available hooks (${HOOKS.length}):
 `));
@@ -5113,8 +5179,12 @@ Available hooks (${HOOKS.length}):
     console.log();
   }
 });
-program2.command("search").argument("<query>", "Search term").description("Search for hooks").action((query) => {
+program2.command("search").argument("<query>", "Search term").option("-j, --json", "Output as JSON", false).description("Search for hooks").action((query, options) => {
   const results = searchHooks(query);
+  if (options.json) {
+    console.log(JSON.stringify(results));
+    return;
+  }
   if (results.length === 0) {
     console.log(chalk2.dim(`No hooks found for "${query}"`));
     return;
@@ -5127,15 +5197,27 @@ Found ${results.length} hook(s):
     console.log(`    ${h.description}`);
   }
 });
-program2.command("remove").alias("rm").argument("<hook>", "Hook to remove").description("Remove an installed hook").action((hook) => {
+program2.command("remove").alias("rm").argument("<hook>", "Hook to remove").option("-j, --json", "Output as JSON", false).description("Remove an installed hook").action((hook, options) => {
   const removed = removeHook(hook);
+  if (options.json) {
+    console.log(JSON.stringify({ hook, removed }));
+    return;
+  }
   if (removed) {
     console.log(chalk2.green(`\u2713 Removed ${hook} (unregistered from Claude settings)`));
   } else {
     console.log(chalk2.red(`\u2717 ${hook} is not installed`));
   }
 });
-program2.command("categories").description("List all categories").action(() => {
+program2.command("categories").option("-j, --json", "Output as JSON", false).description("List all categories").action((options) => {
+  if (options.json) {
+    const result = CATEGORIES.map((cat) => ({
+      name: cat,
+      count: getHooksByCategory(cat).length
+    }));
+    console.log(JSON.stringify(result));
+    return;
+  }
   console.log(chalk2.bold(`
 Categories:
 `));
@@ -5144,10 +5226,22 @@ Categories:
     console.log(`  ${category} (${count})`);
   }
 });
-program2.command("info").argument("<hook>", "Hook name").description("Show detailed info about a hook").action((hook) => {
+program2.command("info").argument("<hook>", "Hook name").option("-j, --json", "Output as JSON", false).description("Show detailed info about a hook").action((hook, options) => {
   const meta = getHook(hook);
   if (!meta) {
-    console.log(chalk2.red(`Hook '${hook}' not found`));
+    if (options.json) {
+      console.log(JSON.stringify({ error: `Hook '${hook}' not found` }));
+    } else {
+      console.log(chalk2.red(`Hook '${hook}' not found`));
+    }
+    return;
+  }
+  const registered = getRegisteredHooks();
+  const isRegistered = registered.includes(meta.name);
+  const installed = getInstalledHooks();
+  const isInstalled = installed.includes(meta.name);
+  if (options.json) {
+    console.log(JSON.stringify({ ...meta, registered: isRegistered, installed: isInstalled }));
     return;
   }
   console.log(chalk2.bold(`
@@ -5156,16 +5250,254 @@ ${meta.displayName}
   console.log(`  ${meta.description}`);
   console.log();
   console.log(`  ${chalk2.dim("Category:")}  ${meta.category}`);
+  console.log(`  ${chalk2.dim("Version:")}   ${meta.version}`);
   console.log(`  ${chalk2.dim("Event:")}     ${meta.event}`);
   console.log(`  ${chalk2.dim("Matcher:")}   ${meta.matcher || "(none)"}`);
   console.log(`  ${chalk2.dim("Tags:")}      ${meta.tags.join(", ")}`);
   console.log(`  ${chalk2.dim("Package:")}   hook-${meta.name}`);
   console.log();
-  const registered = getRegisteredHooks();
-  if (registered.includes(meta.name)) {
+  if (isRegistered) {
     console.log(chalk2.green("  \u25CF Registered in Claude settings"));
   } else {
     console.log(chalk2.dim("  \u25CB Not registered"));
   }
+  if (isInstalled) {
+    console.log(chalk2.green("  \u25CF Installed in .hooks/"));
+  } else {
+    console.log(chalk2.dim("  \u25CB Not installed"));
+  }
+});
+program2.command("doctor").option("-j, --json", "Output as JSON", false).description("Check health of installed hooks").action((options) => {
+  const settingsPath = join2(homedir2(), ".claude", "settings.json");
+  const issues = [];
+  const healthy = [];
+  const settingsExist = existsSync2(settingsPath);
+  if (!settingsExist) {
+    issues.push({ hook: "(settings)", issue: "~/.claude/settings.json not found", severity: "warning" });
+  }
+  const installed = getInstalledHooks();
+  const registered = getRegisteredHooks();
+  for (const name of installed) {
+    const meta = getHook(name);
+    const hookDir = join2(process.cwd(), ".hooks", `hook-${name}`);
+    let hookHealthy = true;
+    const srcDir = join2(hookDir, "src");
+    if (!existsSync2(srcDir)) {
+      issues.push({ hook: name, issue: "Missing src/ directory", severity: "error" });
+      hookHealthy = false;
+    }
+    if (!existsSync2(join2(hookDir, "package.json"))) {
+      issues.push({ hook: name, issue: "Missing package.json", severity: "error" });
+      hookHealthy = false;
+    }
+    if (!registered.includes(name)) {
+      issues.push({ hook: name, issue: "Installed but not registered in Claude settings", severity: "warning" });
+      hookHealthy = false;
+    }
+    if (meta && settingsExist) {
+      try {
+        const settings = JSON.parse(readFileSync2(settingsPath, "utf-8"));
+        const eventHooks = settings.hooks?.[meta.event] || [];
+        const found = eventHooks.some((entry) => entry.hooks?.some((h) => h.command?.includes(`hook-${name}`)));
+        if (registered.includes(name) && !found) {
+          issues.push({ hook: name, issue: `Registered but not under ${meta.event} event`, severity: "error" });
+          hookHealthy = false;
+        }
+      } catch {}
+    }
+    if (hookHealthy) {
+      healthy.push(name);
+    }
+  }
+  for (const name of registered) {
+    if (!installed.includes(name)) {
+      issues.push({ hook: name, issue: "Registered in settings but not installed in .hooks/", severity: "warning" });
+    }
+  }
+  if (options.json) {
+    console.log(JSON.stringify({ healthy, issues, installed, registered }));
+    return;
+  }
+  console.log(chalk2.bold(`
+Hook Health Check
+`));
+  if (installed.length === 0 && registered.length === 0) {
+    console.log(chalk2.dim("  No hooks installed or registered."));
+    console.log(chalk2.dim("  Run: hooks install gitguard"));
+    return;
+  }
+  if (healthy.length > 0) {
+    console.log(chalk2.green(`  \u2713 ${healthy.length} hook(s) healthy:`));
+    for (const name of healthy) {
+      console.log(chalk2.green(`    ${name}`));
+    }
+  }
+  if (issues.length > 0) {
+    console.log();
+    for (const issue of issues) {
+      const icon = issue.severity === "error" ? chalk2.red("\u2717") : chalk2.yellow("!");
+      console.log(`  ${icon} ${chalk2.cyan(issue.hook)}: ${issue.issue}`);
+    }
+  }
+  if (issues.length === 0) {
+    console.log(chalk2.green(`
+  All hooks healthy!`));
+  }
+  console.log();
+});
+program2.command("update").argument("[hooks...]", "Hooks to update (defaults to all installed)").option("-j, --json", "Output as JSON", false).description("Update installed hooks to latest version from package").action((hooks, options) => {
+  const installed = getInstalledHooks();
+  const toUpdate = hooks.length > 0 ? hooks : installed;
+  if (toUpdate.length === 0) {
+    if (options.json) {
+      console.log(JSON.stringify({ updated: [], error: "No hooks installed" }));
+    } else {
+      console.log(chalk2.dim("No hooks installed to update."));
+    }
+    return;
+  }
+  const results = [];
+  for (const name of toUpdate) {
+    if (!installed.includes(name)) {
+      results.push({ hook: name, success: false, error: "Not installed" });
+      continue;
+    }
+    const result = installHook(name, { overwrite: true });
+    results.push(result);
+  }
+  if (options.json) {
+    console.log(JSON.stringify({
+      updated: results.filter((r) => r.success).map((r) => r.hook),
+      failed: results.filter((r) => !r.success).map((r) => ({ hook: r.hook, error: r.error }))
+    }));
+    return;
+  }
+  console.log(chalk2.bold(`
+Updating hooks...
+`));
+  for (const result of results) {
+    if (result.success) {
+      console.log(chalk2.green(`\u2713 ${result.hook} updated`));
+    } else {
+      console.log(chalk2.red(`\u2717 ${result.hook}: ${result.error}`));
+    }
+  }
+});
+program2.command("docs").argument("[hook]", "Hook name (shows general docs if omitted)").option("-j, --json", "Output as JSON", false).description("Show documentation for hooks").action((hook, options) => {
+  if (hook) {
+    const meta = getHook(hook);
+    if (!meta) {
+      if (options.json) {
+        console.log(JSON.stringify({ error: `Hook '${hook}' not found` }));
+      } else {
+        console.log(chalk2.red(`Hook '${hook}' not found`));
+      }
+      return;
+    }
+    const hookPath = getHookPath(hook);
+    const readmePath = join2(hookPath, "README.md");
+    let readme = "";
+    if (existsSync2(readmePath)) {
+      readme = readFileSync2(readmePath, "utf-8");
+    }
+    if (options.json) {
+      console.log(JSON.stringify({ ...meta, readme }));
+      return;
+    }
+    console.log(chalk2.bold(`
+${meta.displayName} v${meta.version}
+`));
+    console.log(`  ${meta.description}
+`);
+    console.log(chalk2.bold("  Configuration:"));
+    console.log(`    Event:    ${meta.event}`);
+    console.log(`    Matcher:  ${meta.matcher || "(all tools)"}`);
+    console.log(`    Package:  hook-${meta.name}`);
+    console.log();
+    console.log(chalk2.bold("  Install:"));
+    console.log(`    hooks install ${meta.name}`);
+    console.log();
+    if (readme) {
+      console.log(chalk2.bold(`  README:
+`));
+      const lines = readme.split(`
+`);
+      for (const line of lines) {
+        console.log(`    ${line}`);
+      }
+    }
+    return;
+  }
+  const generalDocs = {
+    overview: "Claude Code hooks are scripts that run at specific points in a Claude Code session.",
+    events: {
+      PreToolUse: 'Fires before a tool executes. Can block the operation by returning { "decision": "block" }.',
+      PostToolUse: "Fires after a tool executes. Runs asynchronously, cannot block.",
+      Stop: "Fires when a Claude Code session ends. Useful for notifications and cleanup.",
+      Notification: "Fires on notification events like context compaction."
+    },
+    installation: {
+      single: "hooks install gitguard",
+      multiple: "hooks install gitguard checkpoint packageage",
+      category: 'hooks install --category "Git Safety"',
+      all: "hooks install --all"
+    },
+    management: {
+      list: "hooks list",
+      listInstalled: "hooks list --installed",
+      listRegistered: "hooks list --registered",
+      search: "hooks search <query>",
+      info: "hooks info <name>",
+      remove: "hooks remove <name>",
+      update: "hooks update",
+      doctor: "hooks doctor"
+    },
+    structure: {
+      hooksDir: ".hooks/hook-<name>/",
+      settings: "~/.claude/settings.json",
+      hookSource: ".hooks/hook-<name>/src/hook.ts"
+    }
+  };
+  if (options.json) {
+    console.log(JSON.stringify(generalDocs));
+    return;
+  }
+  console.log(chalk2.bold(`
+@hasna/hooks Documentation
+`));
+  console.log(chalk2.bold(`  Overview
+`));
+  console.log(`    ${generalDocs.overview}
+`);
+  console.log(chalk2.bold(`  Hook Events
+`));
+  for (const [event, desc] of Object.entries(generalDocs.events)) {
+    console.log(`    ${chalk2.cyan(event)}`);
+    console.log(`      ${desc}
+`);
+  }
+  console.log(chalk2.bold(`  Installation
+`));
+  for (const [label, cmd] of Object.entries(generalDocs.installation)) {
+    console.log(`    ${chalk2.dim(label + ":")}  ${cmd}`);
+  }
+  console.log(chalk2.bold(`
+  Management
+`));
+  for (const [label, cmd] of Object.entries(generalDocs.management)) {
+    console.log(`    ${chalk2.dim(label + ":")}  ${cmd}`);
+  }
+  console.log(chalk2.bold(`
+  File Structure
+`));
+  for (const [label, path] of Object.entries(generalDocs.structure)) {
+    console.log(`    ${chalk2.dim(label + ":")}  ${path}`);
+  }
+  console.log(chalk2.bold(`
+  Hook-Specific Docs
+`));
+  console.log(`    hooks docs <name>     View README for a specific hook`);
+  console.log(`    hooks docs --json     Machine-readable documentation`);
+  console.log();
 });
 program2.parse();

package/dist/index.js

@@ -177,7 +177,7 @@ import { join, dirname } from "path";
 import { homedir } from "os";
 import { fileURLToPath } from "url";
 var __dirname2 = dirname(fileURLToPath(import.meta.url));
-var HOOKS_DIR = existsSync(join(__dirname2, "..", "..", "hooks")) ? join(__dirname2, "..", "..", "hooks") : join(__dirname2, "..", "hooks");
+var HOOKS_DIR = existsSync(join(__dirname2, "..", "..", "hooks", "hook-gitguard")) ? join(__dirname2, "..", "..", "hooks") : join(__dirname2, "..", "hooks");
 var SETTINGS_PATH = join(homedir(), ".claude", "settings.json");
 function getHookPath(name) {
   const hookName = name.startsWith("hook-") ? name : `hook-${name}`;
@@ -228,6 +228,10 @@ function installHook(name, options = {}) {
     if (!existsSync(destDir)) {
       mkdirSync(destDir, { recursive: true });
     }
+    if (overwrite && existsSync(destPath)) {
+      const { rmSync } = __require("fs");
+      rmSync(destPath, { recursive: true, force: true });
+    }
     cpSync(sourcePath, destPath, { recursive: true });
     registerHookInSettings(shortName);
     updateHooksIndex(destDir);

package/hooks/hook-agentmessages/src/check-messages.ts

@@ -0,0 +1,151 @@
+#!/usr/bin/env bun
+/**
+ * Stop hook for service-message
+ *
+ * Runs when Claude finishes a response. Checks for unread messages
+ * and notifies Claude if there are any pending messages.
+ *
+ * This is efficient because it only runs after Claude completes a turn,
+ * not continuously polling.
+ */
+
+import { homedir } from 'os';
+import { join } from 'path';
+import { readdir } from 'fs/promises';
+
+interface HookInput {
+  session_id: string;
+  cwd: string;
+  hook_event_name: string;
+  stop_hook_active?: boolean;
+}
+
+interface Message {
+  id: string;
+  timestamp: number;
+  from: string;
+  to: string;
+  project: string;
+  subject: string;
+  body: string;
+  read?: boolean;
+}
+
+const SERVICE_DIR = join(homedir(), '.service', 'service-message');
+
+/**
+ * Sanitize ID to prevent path traversal attacks
+ */
+function sanitizeId(id: string): string | null {
+  if (!id || typeof id !== 'string') return null;
+  // Only allow alphanumeric, dash, underscore
+  if (!/^[a-zA-Z0-9_-]+$/.test(id)) return null;
+  // Reject path traversal attempts
+  if (id.includes('..') || id.includes('/') || id.includes('\\')) return null;
+  return id;
+}
+
+async function readJson<T>(path: string): Promise<T | null> {
+  try {
+    const file = Bun.file(path);
+    if (await file.exists()) {
+      return await file.json();
+    }
+  } catch {}
+  return null;
+}
+
+async function getUnreadMessages(agentId: string, projectId?: string): Promise<Message[]> {
+  const messages: Message[] = [];
+  const messagesDir = join(SERVICE_DIR, 'messages');
+
+  try {
+    const rawProjects = projectId ? [projectId] : await readdir(messagesDir);
+    // Sanitize all project names to prevent path traversal
+    const projects = rawProjects.map(p => sanitizeId(p)).filter((p): p is string => p !== null);
+
+    for (const proj of projects) {
+      // Check inbox
+      const inboxDir = join(messagesDir, proj, 'inbox', agentId);
+      try {
+        const files = await readdir(inboxDir);
+        for (const file of files) {
+          if (!file.endsWith('.json')) continue;
+          // Sanitize filename to prevent path traversal
+          const safeFile = sanitizeId(file.replace('.json', ''));
+          if (!safeFile) continue;
+          const msg = await readJson<Message>(join(inboxDir, `${safeFile}.json`));
+          if (msg && !msg.read) {
+            messages.push(msg);
+          }
+        }
+      } catch {}
+
+      // Check broadcast
+      const broadcastDir = join(messagesDir, proj, 'broadcast');
+      try {
+        const files = await readdir(broadcastDir);
+        for (const file of files) {
+          if (!file.endsWith('.json')) continue;
+          // Sanitize filename to prevent path traversal
+          const safeFile = sanitizeId(file.replace('.json', ''));
+          if (!safeFile) continue;
+          const msg = await readJson<Message>(join(broadcastDir, `${safeFile}.json`));
+          if (msg && !msg.read && msg.from !== agentId) {
+            messages.push(msg);
+          }
+        }
+      } catch {}
+    }
+  } catch {}
+
+  return messages.sort((a, b) => b.timestamp - a.timestamp);
+}
+
+async function main() {
+  // Get agent ID from environment (set by session-start hook)
+  const rawAgentId = process.env.SMSG_AGENT_ID;
+  const rawProjectId = process.env.SMSG_PROJECT_ID;
+
+  // Sanitize IDs to prevent path traversal
+  const agentId = rawAgentId ? sanitizeId(rawAgentId) : null;
+  const projectId = rawProjectId ? sanitizeId(rawProjectId) : undefined;
+
+  if (!agentId) {
+    // Agent not configured or invalid, skip silently
+    console.log(JSON.stringify({ continue: true }));
+    return;
+  }
+
+  // Check for unread messages
+  const unreadMessages = await getUnreadMessages(agentId, projectId);
+
+  if (unreadMessages.length === 0) {
+    // No messages, continue normally
+    console.log(JSON.stringify({ continue: true }));
+    return;
+  }
+
+  // Format message summary in a friendly way
+  const msgList = unreadMessages.slice(0, 3).map(msg => {
+    const time = new Date(msg.timestamp).toLocaleTimeString('en-US', { hour: '2-digit', minute: '2-digit' });
+    const preview = msg.body.slice(0, 60).replace(/\n/g, ' ');
+    return `📨 **${msg.subject}** from \`${msg.from}\` (${time})\n   ${preview}${msg.body.length > 60 ? '...' : ''}`;
+  }).join('\n\n');
+
+  const moreNote = unreadMessages.length > 3
+    ? `\n\n_...and ${unreadMessages.length - 3} more message(s)_`
+    : '';
+
+  // Inject message in a friendly, readable format
+  console.log(JSON.stringify({
+    continue: true,
+    stopReason: `📬 **You have ${unreadMessages.length} unread message(s):**\n\n${msgList}${moreNote}\n\n💡 Use \`service-message inbox\` to see all messages or \`service-message read <id>\` to read one.`
+  }));
+}
+
+main().catch(() => {
+  // Don't block on errors
+  console.log(JSON.stringify({ continue: true }));
+  process.exit(0);
+});