@hasna/hooks 0.3.10 → 0.4.0

package/bin/index.js

@@ -861,7 +861,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         this._exitCallback = (err) => {
           if (err.code !== "commander.executeSubCommandAsync") {
             throw err;
-          } else {}
+          }
         };
       }
       return this;
@@ -5346,41 +5346,83 @@ function formatInstallResults(results, extra) {
     }]
   };
 }
+function truncateText(value, max = 160) {
+  const text = String(value ?? "").replace(/\s+/g, " ").trim();
+  if (text.length <= max)
+    return text;
+  return `${text.slice(0, Math.max(0, max - 3))}...`;
+}
+function boundedLimit(value, fallback, max) {
+  if (!Number.isFinite(value) || !value || value <= 0)
+    return fallback;
+  return Math.min(Math.floor(value), max);
+}
+function compactHook(hook) {
+  return {
+    name: hook.name,
+    event: hook.event,
+    matcher: hook.matcher,
+    category: hook.category
+  };
+}
+function compactHookResult(hooks, limit, detail) {
+  const visible = hooks.slice(0, limit).map(compactHook);
+  const omitted = Math.max(0, hooks.length - visible.length);
+  return {
+    hooks: visible,
+    count: visible.length,
+    total: hooks.length,
+    omitted,
+    hint: omitted > 0 ? `Use limit, compact:false, or ${detail} for more detail.` : `Use compact:false or ${detail} for full details.`
+  };
+}
+function compactEvent(row) {
+  return {
+    id: row.id,
+    timestamp: row.timestamp,
+    hook_name: row.hook_name,
+    tool_name: row.tool_name ?? undefined,
+    session_id: row.session_id ? String(row.session_id).slice(0, 12) : undefined,
+    error: row.error ? truncateText(row.error, 180) : undefined,
+    tool_input_preview: row.tool_input ? truncateText(row.tool_input, 180) : undefined
+  };
+}
 function createHooksServer() {
   const server = new McpServer({
     name: "@hasna/hooks",
     version: pkg.version
   });
-  server.tool("hooks_list", "List all available hooks, optionally filtered by category. Use compact:true to get minimal output (name+event+matcher only) \u2014 saves tokens.", {
+  const defineTool = (name, description, schema, handler) => server.tool(name, description, schema, handler);
+  defineTool("hooks_list", "List available hooks. Compact by default; pass compact:false for full HookMeta objects.", {
     category: z.string().optional().describe("Filter by category name (e.g. 'Git Safety', 'Code Quality', 'Security')"),
-    compact: z.boolean().default(false).describe("Return minimal fields only: name, event, matcher. Reduces token usage.")
-  }, async ({ category, compact }) => {
-    const slim = (hooks) => compact ? hooks.map((h) => ({ name: h.name, event: h.event, matcher: h.matcher })) : hooks;
+    compact: z.boolean().default(true).describe("Return compact summaries by default. Set false for full fields."),
+    limit: z.number().default(25).describe("Max compact rows to return")
+  }, async ({ category, compact, limit }) => {
+    const maxRows = boundedLimit(limit, 25, 100);
     if (category) {
       const cat = CATEGORIES.find((c) => c.toLowerCase() === category.toLowerCase());
       if (!cat) {
         return { content: [{ type: "text", text: JSON.stringify({ error: `Unknown category: ${category}`, available: [...CATEGORIES] }) }] };
       }
-      return { content: [{ type: "text", text: JSON.stringify(slim(getHooksByCategory(cat))) }] };
-    }
-    if (compact) {
-      return { content: [{ type: "text", text: JSON.stringify(slim(HOOKS)) }] };
+      const hooks = getHooksByCategory(cat);
+      return { content: [{ type: "text", text: JSON.stringify(compact ? compactHookResult(hooks, maxRows, "hooks_info") : hooks) }] };
     }
     const result = {};
     for (const cat of CATEGORIES) {
       result[cat] = getHooksByCategory(cat);
     }
-    return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    return { content: [{ type: "text", text: JSON.stringify(compact ? compactHookResult(HOOKS, maxRows, "hooks_info") : result) }] };
   });
-  server.tool("hooks_search", "Search for hooks by name, description, or tags. Use compact:true for minimal output to save tokens.", {
+  defineTool("hooks_search", "Search hooks. Compact by default; pass compact:false for full HookMeta objects.", {
     query: z.string().describe("Search query"),
-    compact: z.boolean().default(false).describe("Return minimal fields only: name, event, matcher.")
-  }, async ({ query, compact }) => {
+    compact: z.boolean().default(true).describe("Return compact summaries by default. Set false for full fields."),
+    limit: z.number().default(10).describe("Max compact rows to return")
+  }, async ({ query, compact, limit }) => {
     const results = searchHooks(query);
-    const out = compact ? results.map((h) => ({ name: h.name, event: h.event, matcher: h.matcher })) : results;
+    const out = compact ? compactHookResult(results, boundedLimit(limit, 10, 100), "hooks_info") : results;
     return { content: [{ type: "text", text: JSON.stringify(out) }] };
   });
-  server.tool("hooks_info", "Get detailed information about a specific hook including install status", { name: z.string().describe("Hook name (e.g. 'gitguard', 'checkpoint')") }, async ({ name }) => {
+  defineTool("hooks_info", "Get detailed information about a specific hook including install status", { name: z.string().describe("Hook name (e.g. 'gitguard', 'checkpoint')") }, async ({ name }) => {
     const meta = getHook(name);
     if (!meta) {
       return { content: [{ type: "text", text: JSON.stringify({ error: `Hook '${name}' not found` }) }] };
@@ -5389,7 +5431,7 @@ function createHooksServer() {
     const projectInstalled = getRegisteredHooks("project").includes(meta.name);
     return { content: [{ type: "text", text: JSON.stringify({ ...meta, global: globalInstalled, project: projectInstalled }) }] };
   });
-  server.tool("hooks_install", "Install one or more hooks by registering them in agent settings", {
+  defineTool("hooks_install", "Install one or more hooks by registering them in agent settings", {
     hooks: z.array(z.string()).describe("Hook names to install"),
     scope: z.enum(["global", "project"]).default("global").describe("Install scope"),
     overwrite: z.boolean().default(false).describe("Overwrite if already installed"),
@@ -5398,7 +5440,7 @@ function createHooksServer() {
     const results = hooks.map((name) => installHook(name, { scope, overwrite, profile }));
     return formatInstallResults(results, { scope, profile });
   });
-  server.tool("hooks_install_category", "Install all hooks in a category", {
+  defineTool("hooks_install_category", "Install all hooks in a category", {
     category: z.string().describe("Category name"),
     scope: z.enum(["global", "project"]).default("global").describe("Install scope"),
     overwrite: z.boolean().default(false).describe("Overwrite if already installed")
@@ -5411,21 +5453,21 @@ function createHooksServer() {
     const results = hooks.map((name) => installHook(name, { scope, overwrite }));
     return formatInstallResults(results, { category: cat, scope });
   });
-  server.tool("hooks_install_all", "Install all available hooks", {
+  defineTool("hooks_install_all", "Install all available hooks", {
     scope: z.enum(["global", "project"]).default("global").describe("Install scope"),
     overwrite: z.boolean().default(false).describe("Overwrite if already installed")
   }, async ({ scope, overwrite }) => {
     const results = HOOKS.map((h) => installHook(h.name, { scope, overwrite }));
     return formatInstallResults(results, { scope });
   });
-  server.tool("hooks_remove", "Remove (unregister) a hook from agent settings", {
+  defineTool("hooks_remove", "Remove (unregister) a hook from agent settings", {
     name: z.string().describe("Hook name to remove"),
     scope: z.enum(["global", "project"]).default("global").describe("Scope to remove from")
   }, async ({ name, scope }) => {
     const removed = removeHook(name, scope);
     return { content: [{ type: "text", text: JSON.stringify({ hook: name, removed, scope }) }] };
   });
-  server.tool("hooks_doctor", "Check health of installed hooks \u2014 verifies hook source exists, settings are correct", {
+  defineTool("hooks_doctor", "Check health of installed hooks \u2014 verifies hook source exists, settings are correct", {
     scope: z.enum(["global", "project"]).default("global").describe("Scope to check")
   }, async ({ scope }) => {
     const settingsPath = getSettingsPath(scope);
@@ -5467,14 +5509,17 @@ function createHooksServer() {
     }
     return { content: [{ type: "text", text: JSON.stringify({ healthy: issues.length === 0, healthy_hooks: healthy, issues, registered, scope }) }] };
   });
-  server.tool("hooks_categories", "List all hook categories with counts", {}, async () => {
+  defineTool("hooks_categories", "List all hook categories with counts", {}, async () => {
     const result = CATEGORIES.map((cat) => ({
       name: cat,
       count: getHooksByCategory(cat).length
     }));
     return { content: [{ type: "text", text: JSON.stringify(result) }] };
   });
-  server.tool("hooks_docs", "Get documentation \u2014 general overview or README for a specific hook", { name: z.string().optional().describe("Hook name for specific docs, omit for general docs") }, async ({ name }) => {
+  defineTool("hooks_docs", "Get documentation. Hook README content is summarized by default; pass verbose:true for the full README.", {
+    name: z.string().optional().describe("Hook name for specific docs, omit for general docs"),
+    verbose: z.boolean().default(false).describe("Return full hook README when true")
+  }, async ({ name, verbose }) => {
     if (name) {
       const meta = getHook(name);
       if (!meta) {
@@ -5486,7 +5531,24 @@ function createHooksServer() {
       if (existsSync6(readmePath)) {
         readme = readFileSync4(readmePath, "utf-8");
       }
-      return { content: [{ type: "text", text: JSON.stringify({ ...meta, readme }) }] };
+      if (verbose) {
+        return { content: [{ type: "text", text: JSON.stringify({ ...meta, readme }) }] };
+      }
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            ...compactHook(meta),
+            displayName: meta.displayName,
+            version: meta.version,
+            description: truncateText(meta.description, 220),
+            readme_preview: truncateText(readme, 500),
+            readme_lines: readme ? readme.split(`
+`).length : 0,
+            hint: "Call hooks_docs with verbose:true for the full README or hooks_info for metadata."
+          })
+        }]
+      };
     }
     return {
       content: [{
@@ -5514,17 +5576,39 @@ function createHooksServer() {
       }]
     };
   });
-  server.tool("hooks_registered", "Get list of currently registered hooks for a scope", {
-    scope: z.enum(["global", "project"]).default("global").describe("Scope to check")
-  }, async ({ scope }) => {
+  defineTool("hooks_registered", "Get currently registered hooks for a scope. Compact by default.", {
+    scope: z.enum(["global", "project"]).default("global").describe("Scope to check"),
+    compact: z.boolean().default(true).describe("Return compact summaries by default. Set false for descriptions."),
+    limit: z.number().default(25).describe("Max compact rows to return")
+  }, async ({ scope, compact, limit }) => {
     const registered = getRegisteredHooks(scope);
     const result = registered.map((name) => {
       const meta = getHook(name);
       return { name, event: meta?.event, matcher: meta?.matcher ?? "", version: meta?.version, description: meta?.description };
     });
-    return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    if (!compact)
+      return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    const maxRows = boundedLimit(limit, 25, 100);
+    const visible = result.slice(0, maxRows).map((hook) => ({
+      name: hook.name,
+      event: hook.event,
+      matcher: hook.matcher,
+      version: hook.version
+    }));
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          hooks: visible,
+          count: visible.length,
+          total: result.length,
+          omitted: Math.max(0, result.length - visible.length),
+          hint: "Use compact:false for descriptions or hooks_info for one hook."
+        })
+      }]
+    };
   });
-  server.tool("hooks_run", "Execute a hook programmatically with the given input and return its output", {
+  defineTool("hooks_run", "Execute a hook programmatically with the given input and return its output", {
     name: z.string().describe("Hook name (e.g. 'gitguard', 'checkpoint')"),
     input: z.record(z.string(), z.unknown()).default(() => ({})).describe("Hook input as JSON object (HookInput)"),
     profile: z.string().optional().describe("Agent profile ID to inject into hook input"),
@@ -5588,7 +5672,7 @@ function createHooksServer() {
       }]
     };
   });
-  server.tool("hooks_update", "Re-register installed hooks to pick up new package version (reinstalls with overwrite)", {
+  defineTool("hooks_update", "Re-register installed hooks to pick up new package version (reinstalls with overwrite)", {
     hooks: z.array(z.string()).optional().describe("Hook names to update (omit to update all installed hooks)"),
     scope: z.enum(["global", "project"]).default("global").describe("Scope to update")
   }, async ({ hooks, scope }) => {
@@ -5607,10 +5691,11 @@ function createHooksServer() {
     const failed = results.filter((r) => !r.success).map((r) => ({ hook: r.hook, error: r.error }));
     return { content: [{ type: "text", text: JSON.stringify({ updated, failed, total: results.length }) }] };
   });
-  server.tool("hooks_context", "Get full agent context in one call: installed hooks (with event+matcher), active profile, settings path, and doctor status. Call this once at session start instead of making 4 separate calls.", {
+  defineTool("hooks_context", "Get compact agent context in one call: installed hooks, active profile summary, settings path, and doctor status.", {
     scope: z.enum(["global", "project"]).default("global").describe("Scope to inspect"),
-    profile: z.string().optional().describe("Agent profile ID to include in context")
-  }, async ({ scope, profile }) => {
+    profile: z.string().optional().describe("Agent profile ID to include in context"),
+    verbose: z.boolean().default(false).describe("Include full profile preferences/details when true")
+  }, async ({ scope, profile, verbose }) => {
     const settingsPath = getSettingsPath(scope);
     const registered = getRegisteredHooks(scope);
     const hooks = registered.map((name) => {
@@ -5636,11 +5721,13 @@ function createHooksServer() {
     };
     if (profile) {
       const p = getProfile(profile);
-      ctx.profile = p ?? null;
+      ctx.profile = p && !verbose ? { agent_id: p.agent_id, agent_type: p.agent_type, name: p.name } : p ?? null;
+      if (p && !verbose)
+        ctx.profile_hint = "Use verbose:true for profile preferences.";
     }
     return { content: [{ type: "text", text: JSON.stringify(ctx) }] };
   });
-  server.tool("hooks_preview", "Simulate which installed PreToolUse hooks would fire for a given tool call and what decision each returns. Use this to understand your hook environment before taking an action.", {
+  defineTool("hooks_preview", "Simulate which installed PreToolUse hooks would fire for a given tool call and what decision each returns. Use this to understand your hook environment before taking an action.", {
     tool_name: z.string().describe("Tool name to simulate (e.g. 'Bash', 'Write', 'Edit')"),
     tool_input: z.record(z.string(), z.unknown()).default(() => ({})).describe("Tool input to pass to matching hooks"),
     scope: z.enum(["global", "project"]).default("global").describe("Scope to check"),
@@ -5705,7 +5792,7 @@ function createHooksServer() {
       }]
     };
   });
-  server.tool("hooks_setup", "Single-shot agent onboarding: create an agent profile + install recommended hooks in one call. Ideal for agents setting up hooks at session start.", {
+  defineTool("hooks_setup", "Single-shot agent onboarding: create an agent profile + install recommended hooks in one call. Ideal for agents setting up hooks at session start.", {
     agent_type: z.enum(["claude", "gemini", "custom"]).default("claude").describe("Type of AI agent"),
     name: z.string().optional().describe("Optional display name for the agent"),
     hooks: z.array(z.string()).optional().describe("Hook names to install (omit for sensible defaults: gitguard, checkpoint, checktests, protectfiles)"),
@@ -5723,7 +5810,7 @@ function createHooksServer() {
       }]
     };
   });
-  server.tool("hooks_batch_run", "Run multiple hooks in parallel in a single call. Returns all results at once \u2014 more efficient than N separate hooks_run calls.", {
+  defineTool("hooks_batch_run", "Run multiple hooks in parallel in a single call. Returns all results at once \u2014 more efficient than N separate hooks_run calls.", {
     hooks: z.array(z.object({
       name: z.string().describe("Hook name"),
       input: z.record(z.string(), z.unknown()).default(() => ({})).describe("Hook input JSON")
@@ -5761,7 +5848,7 @@ function createHooksServer() {
     }));
     return { content: [{ type: "text", text: JSON.stringify({ results, count: results.length }) }] };
   });
-  server.tool("hooks_disable", "Temporarily disable a registered hook without removing it. Stores disabled list in settings under hooks.__disabled.", {
+  defineTool("hooks_disable", "Temporarily disable a registered hook without removing it. Stores disabled list in settings under hooks.__disabled.", {
     name: z.string().describe("Hook name to disable"),
     scope: z.enum(["global", "project"]).default("global").describe("Scope")
   }, async ({ name, scope }) => {
@@ -5784,7 +5871,7 @@ function createHooksServer() {
 `);
     return { content: [{ type: "text", text: JSON.stringify({ hook: name, disabled: true, scope }) }] };
   });
-  server.tool("hooks_enable", "Re-enable a previously disabled hook.", {
+  defineTool("hooks_enable", "Re-enable a previously disabled hook.", {
     name: z.string().describe("Hook name to enable"),
     scope: z.enum(["global", "project"]).default("global").describe("Scope")
   }, async ({ name, scope }) => {
@@ -5804,25 +5891,50 @@ function createHooksServer() {
     }
     return { content: [{ type: "text", text: JSON.stringify({ hook: name, disabled: false, scope }) }] };
   });
-  server.tool("hooks_init", "Register a new agent profile \u2014 returns a unique agent_id for use with hook installation and execution", {
+  defineTool("hooks_init", "Register a new agent profile \u2014 returns a unique agent_id for use with hook installation and execution", {
     agent_type: z.enum(["claude", "gemini", "custom"]).default("claude").describe("Type of AI agent"),
     name: z.string().optional().describe("Optional display name for the agent")
   }, async ({ agent_type, name }) => {
     const profile = createProfile({ agent_type, name });
     return { content: [{ type: "text", text: JSON.stringify(profile) }] };
   });
-  server.tool("hooks_profiles", "List all registered agent profiles", {}, async () => {
+  defineTool("hooks_profiles", "List registered agent profiles. Compact by default.", {
+    compact: z.boolean().default(true).describe("Return compact summaries by default. Set false for full profiles."),
+    limit: z.number().default(25).describe("Max compact rows to return")
+  }, async ({ compact, limit }) => {
     const profiles = listProfiles();
-    return { content: [{ type: "text", text: JSON.stringify(profiles) }] };
+    if (!compact)
+      return { content: [{ type: "text", text: JSON.stringify(profiles) }] };
+    const maxRows = boundedLimit(limit, 25, 100);
+    const visible = profiles.slice(0, maxRows).map((profile) => ({
+      agent_id: profile.agent_id,
+      agent_type: profile.agent_type,
+      name: profile.name,
+      last_seen_at: profile.last_seen_at
+    }));
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          profiles: visible,
+          count: visible.length,
+          total: profiles.length,
+          omitted: Math.max(0, profiles.length - visible.length),
+          hint: "Use compact:false for full profile preferences."
+        })
+      }]
+    };
   });
-  server.tool("hooks_log_list", "List hook events from SQLite (~/.hasna/hooks/hooks.db). Filter by hook name, session ID, or time range.", {
+  defineTool("hooks_log_list", "List hook events from SQLite. Compact summaries by default; set compact:false for full event rows.", {
     hook_name: z.string().optional().describe("Filter by hook name (e.g. 'sessionlog', 'costwatch')"),
     session_id: z.string().optional().describe("Filter by session ID prefix"),
-    limit: z.number().default(50).describe("Max number of events to return"),
-    since: z.string().optional().describe("ISO timestamp or duration string (e.g. '1h', '30m', '7d') to filter from")
-  }, async ({ hook_name, session_id, limit, since }) => {
+    limit: z.number().optional().describe("Max number of events to return. Defaults to 20 compact rows or 50 full rows."),
+    since: z.string().optional().describe("ISO timestamp or duration string (e.g. '1h', '30m', '7d') to filter from"),
+    compact: z.boolean().default(true).describe("Return compact event summaries by default. Set false for full rows.")
+  }, async ({ hook_name, session_id, limit, since, compact }) => {
     const { getDb: getDb2 } = await Promise.resolve().then(() => (init_db(), exports_db));
     const db = getDb2();
+    const maxRows = boundedLimit(limit, compact ? 20 : 50, compact ? 100 : 500);
     function parseDuration(s) {
       const m = s.match(/^(\d+)(s|m|h|d)$/);
       if (!m)
@@ -5849,24 +5961,48 @@ function createHooksServer() {
       }
     }
     sql += " ORDER BY timestamp DESC LIMIT ?";
-    params.push(limit);
+    params.push(maxRows);
     const rows = db.query(sql).all(...params);
-    return { content: [{ type: "text", text: JSON.stringify({ events: rows, count: rows.length }) }] };
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          events: compact ? rows.map(compactEvent) : rows,
+          count: rows.length,
+          compact,
+          hint: compact ? "Use compact:false for full tool_input/output fields." : undefined
+        })
+      }]
+    };
   });
-  server.tool("hooks_log_tail", "Show the most recent hook events from SQLite.", {
-    n: z.number().default(20).describe("Number of most recent events to return")
-  }, async ({ n }) => {
+  defineTool("hooks_log_tail", "Show recent hook events from SQLite. Compact summaries by default.", {
+    n: z.number().default(20).describe("Number of most recent events to return"),
+    compact: z.boolean().default(true).describe("Return compact event summaries by default. Set false for full rows.")
+  }, async ({ n, compact }) => {
     const { getDb: getDb2 } = await Promise.resolve().then(() => (init_db(), exports_db));
     const db = getDb2();
-    const rows = db.query("SELECT * FROM hook_events ORDER BY timestamp DESC LIMIT ?").all(n);
-    return { content: [{ type: "text", text: JSON.stringify({ events: rows, count: rows.length }) }] };
+    const maxRows = boundedLimit(n, 20, compact ? 100 : 500);
+    const rows = db.query("SELECT * FROM hook_events ORDER BY timestamp DESC LIMIT ?").all(maxRows);
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          events: compact ? rows.map(compactEvent) : rows,
+          count: rows.length,
+          compact,
+          hint: compact ? "Use compact:false for full tool_input/output fields." : undefined
+        })
+      }]
+    };
   });
-  server.tool("hooks_log_errors", "Show hook events that contain errors, optionally filtered by time range.", {
+  defineTool("hooks_log_errors", "Show hook events that contain errors. Compact summaries by default.", {
     since: z.string().default("24h").describe("Duration string (e.g. '1h', '30m', '7d') or ISO timestamp"),
-    limit: z.number().default(50).describe("Max number of error events to return")
-  }, async ({ since, limit }) => {
+    limit: z.number().optional().describe("Max number of error events to return. Defaults to 20 compact rows or 50 full rows."),
+    compact: z.boolean().default(true).describe("Return compact event summaries by default. Set false for full rows.")
+  }, async ({ since, limit, compact }) => {
     const { getDb: getDb2 } = await Promise.resolve().then(() => (init_db(), exports_db));
     const db = getDb2();
+    const maxRows = boundedLimit(limit, compact ? 20 : 50, compact ? 100 : 500);
     function parseDuration(s) {
       const m = s.match(/^(\d+)(s|m|h|d)$/);
       if (!m)
@@ -5876,10 +6012,20 @@ function createHooksServer() {
       return new Date(Date.now() - n * ms).toISOString();
     }
     const ts = since.match(/^\d{4}/) ? since : parseDuration(since);
-    const rows = db.query("SELECT * FROM hook_events WHERE error IS NOT NULL AND timestamp >= ? ORDER BY timestamp DESC LIMIT ?").all(ts, limit);
-    return { content: [{ type: "text", text: JSON.stringify({ events: rows, count: rows.length }) }] };
+    const rows = db.query("SELECT * FROM hook_events WHERE error IS NOT NULL AND timestamp >= ? ORDER BY timestamp DESC LIMIT ?").all(ts, maxRows);
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          events: compact ? rows.map(compactEvent) : rows,
+          count: rows.length,
+          compact,
+          hint: compact ? "Use compact:false for full tool_input/output fields." : undefined
+        })
+      }]
+    };
   });
-  server.tool("hooks_log_summary", "Summarize hook execution: counts per hook, error rates, and recent activity.", {
+  defineTool("hooks_log_summary", "Summarize hook execution: counts per hook, error rates, and recent activity.", {
     since: z.string().default("24h").describe("Duration string (e.g. '1h', '24h', '7d') or ISO timestamp")
   }, async ({ since }) => {
     const { getDb: getDb2 } = await Promise.resolve().then(() => (init_db(), exports_db));
@@ -5913,11 +6059,11 @@ function createHooksServer() {
       }]
     };
   });
-  server.tool("storage_status", "Show hooks storage sync configuration and local sync history.", {}, async () => ({ content: [{ type: "text", text: JSON.stringify(getStorageStatus()) }] }));
-  server.tool("storage_push", "Push local hook data to storage PostgreSQL.", { tables: z.array(z.string()).optional() }, async (params) => ({ content: [{ type: "text", text: JSON.stringify(await storagePush(params.tables ? { tables: params.tables } : undefined)) }] }));
-  server.tool("storage_pull", "Pull hook data from storage PostgreSQL to local SQLite.", { tables: z.array(z.string()).optional() }, async (params) => ({ content: [{ type: "text", text: JSON.stringify(await storagePull(params.tables ? { tables: params.tables } : undefined)) }] }));
-  server.tool("storage_sync", "Bidirectional hooks storage sync: pull then push.", { tables: z.array(z.string()).optional() }, async (params) => ({ content: [{ type: "text", text: JSON.stringify(await storageSync(params.tables ? { tables: params.tables } : undefined)) }] }));
-  server.tool("send_feedback", "Send feedback about this service", {
+  defineTool("storage_status", "Show hooks storage sync configuration and local sync history.", {}, async () => ({ content: [{ type: "text", text: JSON.stringify(getStorageStatus()) }] }));
+  defineTool("storage_push", "Push local hook data to storage PostgreSQL.", { tables: z.array(z.string()).optional() }, async (params) => ({ content: [{ type: "text", text: JSON.stringify(await storagePush(params.tables ? { tables: params.tables } : undefined)) }] }));
+  defineTool("storage_pull", "Pull hook data from storage PostgreSQL to local SQLite.", { tables: z.array(z.string()).optional() }, async (params) => ({ content: [{ type: "text", text: JSON.stringify(await storagePull(params.tables ? { tables: params.tables } : undefined)) }] }));
+  defineTool("storage_sync", "Bidirectional hooks storage sync: pull then push.", { tables: z.array(z.string()).optional() }, async (params) => ({ content: [{ type: "text", text: JSON.stringify(await storageSync(params.tables ? { tables: params.tables } : undefined)) }] }));
+  defineTool("send_feedback", "Send feedback about this service", {
     message: z.string(),
     email: z.string().optional(),
     category: z.enum(["bug", "feature", "general"]).optional()
@@ -5936,7 +6082,7 @@ function createHooksServer() {
       return { content: [{ type: "text", text: String(e) }], isError: true };
     }
   });
-  server.tool("register_agent", "Register an agent session. Returns agent_id. Auto-triggers a heartbeat.", {
+  defineTool("register_agent", "Register an agent session. Returns agent_id. Auto-triggers a heartbeat.", {
     name: z.string(),
     session_id: z.string().optional()
   }, async (params) => {
@@ -5952,7 +6098,7 @@ function createHooksServer() {
     _hooksAgents.set(id, ag);
     return { content: [{ type: "text", text: JSON.stringify(ag) }] };
   });
-  server.tool("heartbeat", "Update last_seen_at to signal agent is active.", {
+  defineTool("heartbeat", "Update last_seen_at to signal agent is active.", {
     agent_id: z.string()
   }, async (params) => {
     const ag = _hooksAgents.get(params.agent_id);
@@ -5961,7 +6107,7 @@ function createHooksServer() {
     ag.last_seen_at = new Date().toISOString();
     return { content: [{ type: "text", text: JSON.stringify({ agent_id: ag.id, last_seen_at: ag.last_seen_at }) }] };
   });
-  server.tool("set_focus", "Set active project context for this agent session.", {
+  defineTool("set_focus", "Set active project context for this agent session.", {
     agent_id: z.string(),
     project_id: z.string().optional()
   }, async (params) => {
@@ -5971,8 +6117,32 @@ function createHooksServer() {
     ag.project_id = params.project_id;
     return { content: [{ type: "text", text: JSON.stringify({ agent_id: ag.id, project_id: ag.project_id ?? null }) }] };
   });
-  server.tool("list_agents", "List all registered agents.", {}, async () => {
-    return { content: [{ type: "text", text: JSON.stringify([..._hooksAgents.values()]) }] };
+  defineTool("list_agents", "List registered agents. Compact by default.", {
+    compact: z.boolean().default(true).describe("Return compact agent summaries by default. Set false for full records."),
+    limit: z.number().default(25).describe("Max compact rows to return")
+  }, async ({ compact, limit }) => {
+    const agents = [..._hooksAgents.values()];
+    if (!compact)
+      return { content: [{ type: "text", text: JSON.stringify(agents) }] };
+    const maxRows = boundedLimit(limit, 25, 100);
+    const visible = agents.slice(0, maxRows).map((agent) => ({
+      id: agent.id,
+      name: agent.name,
+      project_id: agent.project_id,
+      last_seen_at: agent.last_seen_at
+    }));
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          agents: visible,
+          count: visible.length,
+          total: agents.length,
+          omitted: Math.max(0, agents.length - visible.length),
+          hint: "Use compact:false for session_id and full records."
+        })
+      }]
+    };
   });
   return server;
 }
@@ -6100,6 +6270,7 @@ var init_http = () => {};
 
 // node_modules/@hasna/events/dist/commander.js
 import { chmod, mkdir, readFile, rename, writeFile } from "fs/promises";
+import { Buffer as Buffer2 } from "buffer";
 import { existsSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
@@ -6204,6 +6375,9 @@ function channelMatchesEvent(channel, event) {
 }
 var HASNA_EVENTS_DIR_ENV = "HASNA_EVENTS_DIR";
 var HASNA_EVENTS_HOME_ENV = "HASNA_EVENTS_HOME";
+var LOCAL_JSON_EVENT_CURSOR_PREFIX = "local-json-v1:";
+var DEFAULT_EVENT_PAGE_LIMIT = 100;
+var MAX_EVENT_PAGE_LIMIT = 1000;
 function getEventsDataDir(override) {
   return override || process.env[HASNA_EVENTS_DIR_ENV] || process.env[HASNA_EVENTS_HOME_ENV] || join(homedir(), ".hasna", "events");
 }
@@ -6217,11 +6391,13 @@ function getActiveEventsDirEnv() {
 
 class JsonEventsStore {
   dataDir;
+  runtime;
   channelsPath;
   eventsPath;
   deliveriesPath;
   constructor(dataDir = getEventsDataDir()) {
     this.dataDir = dataDir;
+    this.runtime = localJsonRuntime(dataDir);
     this.channelsPath = join(dataDir, "channels.json");
     this.eventsPath = join(dataDir, "events.json");
     this.deliveriesPath = join(dataDir, "deliveries.json");
@@ -6269,13 +6445,58 @@ class JsonEventsStore {
     await this.writeJson(this.eventsPath, events);
     return event;
   }
-  async listEvents() {
+  async appendEventOnce(event, options = {}) {
     await this.init();
-    return this.readJson(this.eventsPath, []);
+    const events = await this.readJson(this.eventsPath, []);
+    const dedupe = options.dedupe !== false;
+    if (dedupe) {
+      const existing = findEventByIdentity(events, { id: event.id, dedupeKey: event.dedupeKey });
+      if (existing) {
+        return {
+          event: existing,
+          stored: false,
+          deduped: true,
+          identity: { id: existing.id, dedupeKey: existing.dedupeKey }
+        };
+      }
+    }
+    events.push(event);
+    await this.writeJson(this.eventsPath, events);
+    return {
+      event,
+      stored: true,
+      deduped: false,
+      identity: { id: event.id, dedupeKey: event.dedupeKey }
+    };
+  }
+  async listEvents(options = {}) {
+    await this.init();
+    const events = await this.readJson(this.eventsPath, []);
+    return queryEvents(events, options);
+  }
+  async listEventsPage(options = {}) {
+    await this.init();
+    const events = await this.readJson(this.eventsPath, []);
+    const queried = queryEvents(events, {
+      eventId: options.eventId,
+      source: options.source,
+      type: options.type
+    });
+    const offset = decodeLocalJsonEventCursor(options.cursor, options);
+    const limit = normalizeEventPageLimit(options.limit);
+    const pageEvents = queried.slice(offset, offset + limit);
+    const nextOffset = offset + pageEvents.length;
+    const hasMore = nextOffset < queried.length;
+    return {
+      events: pageEvents,
+      cursor: options.cursor,
+      nextCursor: hasMore ? encodeLocalJsonEventCursor(nextOffset, options) : undefined,
+      hasMore
+    };
   }
   async findEventByIdentity(identity) {
     const events = await this.listEvents();
-    return events.find((event) => identity.id !== undefined && event.id === identity.id || identity.dedupeKey !== undefined && event.dedupeKey === identity.dedupeKey);
+    return findEventByIdentity(events, identity);
   }
   async appendDelivery(result) {
     await this.init();
@@ -6326,6 +6547,83 @@ class JsonEventsStore {
     });
   }
 }
+function localJsonRuntime(dataDir = getEventsDataDir()) {
+  return {
+    mode: "local-files",
+    name: "json-events-store",
+    remote: false,
+    localFiles: true,
+    localSqlite: false,
+    postgres: false,
+    s3: false,
+    aws: false,
+    durable: true,
+    idempotency: "best-effort-local",
+    replayCursors: true,
+    description: `Local JSON files in ${dataDir}; no SQLite, Postgres, S3, or AWS runtime is configured by this store.`
+  };
+}
+function encodeLocalJsonEventCursor(offset, options = {}) {
+  if (!Number.isInteger(offset) || offset < 0)
+    throw new Error(`Invalid event cursor offset: ${offset}`);
+  const payload = {
+    offset,
+    eventId: options.eventId,
+    source: options.source,
+    type: options.type
+  };
+  return `${LOCAL_JSON_EVENT_CURSOR_PREFIX}${Buffer2.from(JSON.stringify(payload), "utf-8").toString("base64url")}`;
+}
+function decodeLocalJsonEventCursor(cursor, options = {}) {
+  if (!cursor)
+    return 0;
+  if (!cursor.startsWith(LOCAL_JSON_EVENT_CURSOR_PREFIX))
+    throw new Error(`Invalid local JSON event cursor: ${cursor}`);
+  const rawPayload = cursor.slice(LOCAL_JSON_EVENT_CURSOR_PREFIX.length);
+  let payload;
+  try {
+    payload = JSON.parse(Buffer2.from(rawPayload, "base64url").toString("utf-8"));
+  } catch {
+    throw new Error(`Invalid local JSON event cursor: ${cursor}`);
+  }
+  const offset = payload.offset;
+  if (!Number.isInteger(offset) || offset < 0)
+    throw new Error(`Invalid local JSON event cursor: ${cursor}`);
+  assertCursorFilter("eventId", payload.eventId, options.eventId);
+  assertCursorFilter("source", payload.source, options.source);
+  assertCursorFilter("type", payload.type, options.type);
+  return offset;
+}
+function normalizeEventPageLimit(limit) {
+  if (limit === undefined)
+    return DEFAULT_EVENT_PAGE_LIMIT;
+  if (!Number.isInteger(limit) || limit < 1)
+    throw new Error(`Event page limit must be a positive integer, got ${limit}`);
+  return Math.min(limit, MAX_EVENT_PAGE_LIMIT);
+}
+function queryEvents(events, options) {
+  let rows = events;
+  if (options.eventId)
+    rows = rows.filter((event) => event.id === options.eventId);
+  if (options.source)
+    rows = rows.filter((event) => event.source === options.source);
+  if (options.type)
+    rows = rows.filter((event) => event.type === options.type);
+  if (options.cursor) {
+    const offset = decodeLocalJsonEventCursor(options.cursor, options);
+    rows = rows.slice(offset);
+  }
+  if (options.limit !== undefined)
+    rows = rows.slice(0, normalizeEventPageLimit(options.limit));
+  return rows;
+}
+function assertCursorFilter(name, cursorValue, optionValue) {
+  if (cursorValue !== optionValue)
+    throw new Error(`Local JSON event cursor ${name} filter mismatch`);
+}
+function findEventByIdentity(events, identity) {
+  return events.find((event) => identity.id !== undefined && event.id === identity.id || identity.dedupeKey !== undefined && event.dedupeKey === identity.dedupeKey);
+}
 async function getEventsStatus(dataDir) {
   const store = new JsonEventsStore(dataDir);
   await store.init();
@@ -6342,6 +6640,7 @@ async function getEventsStatus(dataDir) {
     service: "events",
     schemaVersion: "1.0",
     dataDir: store.dataDir,
+    storage: store.runtime,
     env: {
       primary: HASNA_EVENTS_DIR_ENV,
       fallback: HASNA_EVENTS_HOME_ENV,
@@ -6528,6 +6827,51 @@ function createDeliveryResult(event, channel, attempts) {
     completedAt: attempts.at(-1)?.completedAt ?? now()
   };
 }
+
+class EventValidationError extends Error {
+  eventType;
+  issues;
+  constructor(eventType, issues) {
+    const detail = issues.map((issue) => `${issue.path || "<root>"}: ${issue.message}`).join("; ");
+    super(`Event validation failed for type "${eventType}": ${detail}`);
+    this.name = "EventValidationError";
+    this.eventType = eventType;
+    this.issues = issues;
+  }
+}
+
+class EventTypeCatalog {
+  definitions = new Map;
+  register(definition) {
+    this.definitions.set(definition.type, definition);
+    return this;
+  }
+  unregister(type) {
+    return this.definitions.delete(type);
+  }
+  has(type) {
+    return this.definitions.has(type);
+  }
+  get(type) {
+    return this.definitions.get(type);
+  }
+  list() {
+    return [...this.definitions.values()];
+  }
+  validateEvent(event) {
+    const definition = this.definitions.get(event.type);
+    if (!definition)
+      return { ok: true };
+    return definition.validate(event.data, event);
+  }
+  assertEventValid(event) {
+    const result = this.validateEvent(event);
+    if (!result.ok) {
+      throw new EventValidationError(event.type, result.issues);
+    }
+  }
+}
+var defaultEventTypeCatalog = new EventTypeCatalog;
 function createEvent(input) {
   return {
     id: input.id ?? randomUUID2(),
@@ -6548,10 +6892,14 @@ class EventsClient {
   store;
   redactors;
   transportOptions;
+  catalog;
+  validateCatalogTypes;
   constructor(options = {}) {
     this.store = options.store ?? new JsonEventsStore(options.dataDir);
     this.redactors = options.redactors ?? [];
     this.transportOptions = { fetchImpl: options.fetchImpl };
+    this.catalog = options.catalog ?? defaultEventTypeCatalog;
+    this.validateCatalogTypes = options.validateCatalogTypes ?? false;
   }
   async addChannel(input) {
     const timestamp = new Date().toISOString();
@@ -6569,18 +6917,40 @@ class EventsClient {
   }
   async emit(input, options = {}) {
     const event = options.redactSensitiveData === false ? createEvent(input) : redactSensitiveKeys(createEvent(input));
-    if (options.dedupe !== false) {
-      const existing = await this.store.findEventByIdentity({ id: input.id, dedupeKey: event.dedupeKey });
-      if (existing) {
-        return { event: existing, deliveries: [], deduped: true };
-      }
-    }
-    await this.store.appendEvent(event);
-    const deliveries = options.deliver === false ? [] : await this.deliver(event);
-    return { event, deliveries, deduped: false };
-  }
-  async listEvents() {
-    return this.store.listEvents();
+    if (options.validate ?? this.validateCatalogTypes) {
+      this.catalog.assertEventValid(event);
+    }
+    const append = await this.appendEvent(event, { dedupe: options.dedupe !== false });
+    if (append.deduped) {
+      return { event: append.event, deliveries: [], deduped: true };
+    }
+    const deliveries = options.deliver === false ? [] : await this.deliver(append.event);
+    return { event: append.event, deliveries, deduped: false };
+  }
+  async listEvents(options = {}) {
+    if (Object.keys(options).length === 0)
+      return this.store.listEvents();
+    return queryClientEvents(await this.store.listEvents(), options);
+  }
+  async listEventsPage(options = {}) {
+    if (this.store.listEventsPage)
+      return this.store.listEventsPage(options);
+    const events = queryClientEvents(await this.store.listEvents(), {
+      eventId: options.eventId,
+      source: options.source,
+      type: options.type
+    });
+    const offset = decodeLocalJsonEventCursor(options.cursor, options);
+    const limit = normalizeEventPageLimit(options.limit);
+    const pageEvents = events.slice(offset, offset + limit);
+    const nextOffset = offset + pageEvents.length;
+    const hasMore = nextOffset < events.length;
+    return {
+      events: pageEvents,
+      cursor: options.cursor,
+      nextCursor: hasMore ? encodeLocalJsonEventCursor(nextOffset, options) : undefined,
+      hasMore
+    };
   }
   async listDeliveries() {
     return this.store.listDeliveries();
@@ -6648,22 +7018,37 @@ class EventsClient {
     return result;
   }
   async replay(options = {}) {
-    const events = (await this.store.listEvents()).filter((event) => {
-      if (options.eventId && event.id !== options.eventId)
-        return false;
-      if (options.source && event.source !== options.source)
-        return false;
-      if (options.type && event.type !== options.type)
-        return false;
-      return true;
-    });
+    const page = options.cursor || options.limit !== undefined ? await this.listEventsPage(options) : { events: await this.listEvents(options), hasMore: false };
     if (options.dryRun)
-      return { events, deliveries: [] };
+      return { events: page.events, deliveries: [], cursor: page.cursor, nextCursor: page.nextCursor, hasMore: page.hasMore };
     const deliveries = [];
-    for (const event of events) {
+    for (const event of page.events) {
       deliveries.push(...await this.deliver(event));
     }
-    return { events, deliveries };
+    return { events: page.events, deliveries, cursor: page.cursor, nextCursor: page.nextCursor, hasMore: page.hasMore };
+  }
+  async appendEvent(event, options) {
+    if (this.store.appendEventOnce) {
+      return this.store.appendEventOnce(event, { dedupe: options.dedupe });
+    }
+    if (options.dedupe) {
+      const existing = await this.store.findEventByIdentity({ id: event.id, dedupeKey: event.dedupeKey });
+      if (existing) {
+        return {
+          event: existing,
+          stored: false,
+          deduped: true,
+          identity: { id: existing.id, dedupeKey: existing.dedupeKey }
+        };
+      }
+    }
+    const stored = await this.store.appendEvent(event);
+    return {
+      event: stored,
+      stored: true,
+      deduped: false,
+      identity: { id: stored.id, dedupeKey: stored.dedupeKey }
+    };
   }
   async applyRedaction(event, channel) {
     let next = redactPaths(event, channel.redact?.paths ?? [], channel.redact?.replacement ?? "[REDACTED]");
@@ -6740,6 +7125,20 @@ function setPath(input, path, replacement) {
   if (last && last in cursor)
     cursor[last] = replacement;
 }
+function queryClientEvents(events, options) {
+  let rows = events;
+  if (options.eventId)
+    rows = rows.filter((event) => event.id === options.eventId);
+  if (options.source)
+    rows = rows.filter((event) => event.source === options.source);
+  if (options.type)
+    rows = rows.filter((event) => event.type === options.type);
+  if (options.cursor)
+    rows = rows.slice(decodeLocalJsonEventCursor(options.cursor, options));
+  if (options.limit !== undefined)
+    rows = rows.slice(0, normalizeEventPageLimit(options.limit));
+  return rows;
+}
 function normalizeTime(value) {
   if (!value)
     return new Date().toISOString();
@@ -6822,6 +7221,7 @@ function parseMatcherExpression(value, label) {
     negated: false
   };
 }
+var DEFAULT_EVENT_LIST_LIMIT = 100;
 function parseJsonObject(value, fallback) {
   if (!value)
     return fallback;
@@ -6854,6 +7254,14 @@ function print(value, json, text) {
   else
     console.log(text);
 }
+function fail(error, json) {
+  const message = error instanceof Error ? error.message : String(error);
+  if (json)
+    console.log(JSON.stringify({ error: message }, null, 2));
+  else
+    console.error(message);
+  process.exitCode = 1;
+}
 function hasJsonOption(options) {
   return Boolean(options?.json || options?.opts?.().json || options?.optsWithGlobals?.().json || options?.parent?.opts?.().json || options?.parent?.optsWithGlobals?.().json);
 }
@@ -6908,26 +7316,36 @@ function registerChannelCommands(program, options) {
     print({ removed }, wantsJson(actionOptions, command), removed ? `Removed ${id}` : `Channel not found: ${id}`);
   });
   channels.command("test").description("Send a test event to one channel").argument("<id>", "Channel identifier").option("--source <source>", "Event source override").option("--type <type>", "Event type", "events.test").option("--subject <subject>", "Event subject").option("--message <message>", "Event message", "Hasna events test delivery").option("--data <json>", "Event data JSON object").option("--metadata <json>", "Event metadata JSON object").option("--honor-filters", "Skip delivery when the sample event does not match channel filters", false).option("-j, --json", "Print JSON output", false).action(async (id, actionOptions, command) => {
-    const result = await createClient(options).testChannel(id, {
-      source: actionOptions.source ?? options.source,
-      type: actionOptions.type,
-      subject: actionOptions.subject ?? id,
-      message: actionOptions.message,
-      data: parseJsonObject(actionOptions.data, { test: true }),
-      metadata: parseJsonObject(actionOptions.metadata, {})
-    }, { honorFilters: actionOptions.honorFilters });
-    print(result, wantsJson(actionOptions, command), `${result.status}: ${result.channelId}`);
+    const json = wantsJson(actionOptions, command);
+    try {
+      const result = await createClient(options).testChannel(id, {
+        source: actionOptions.source ?? options.source,
+        type: actionOptions.type,
+        subject: actionOptions.subject ?? id,
+        message: actionOptions.message,
+        data: parseJsonObject(actionOptions.data, { test: true }),
+        metadata: parseJsonObject(actionOptions.metadata, {})
+      }, { honorFilters: actionOptions.honorFilters });
+      print(result, json, `${result.status}: ${result.channelId}`);
+    } catch (error) {
+      fail(error, json);
+    }
   });
   channels.command("match").description("Check whether a sample event matches one channel without delivering").argument("<id>", "Channel identifier").option("--source <source>", "Event source override").option("--type <type>", "Event type", "events.test").option("--subject <subject>", "Event subject").option("--message <message>", "Event message", "Hasna events match preview").option("--data <json>", "Event data JSON object").option("--metadata <json>", "Event metadata JSON object").option("-j, --json", "Print JSON output", false).action(async (id, actionOptions, command) => {
-    const result = await createClient(options).matchChannel(id, {
-      source: actionOptions.source ?? options.source,
-      type: actionOptions.type,
-      subject: actionOptions.subject ?? id,
-      message: actionOptions.message,
-      data: parseJsonObject(actionOptions.data, { test: true }),
-      metadata: parseJsonObject(actionOptions.metadata, {})
-    });
-    print(result, wantsJson(actionOptions, command), `${result.matched ? "matched" : "skipped"}: ${result.channelId}`);
+    const json = wantsJson(actionOptions, command);
+    try {
+      const result = await createClient(options).matchChannel(id, {
+        source: actionOptions.source ?? options.source,
+        type: actionOptions.type,
+        subject: actionOptions.subject ?? id,
+        message: actionOptions.message,
+        data: parseJsonObject(actionOptions.data, { test: true }),
+        metadata: parseJsonObject(actionOptions.metadata, {})
+      });
+      print(result, json, `${result.matched ? "matched" : "skipped"}: ${result.channelId}`);
+    } catch (error) {
+      fail(error, json);
+    }
   });
   return channels;
 }
@@ -6946,7 +7364,8 @@ function registerEventCommands(program, options) {
     }, { deliver: actionOptions.deliver, dedupe: actionOptions.dedupe });
     print(result, wantsJson(actionOptions, command), `${result.deduped ? "Deduped" : "Emitted"} ${result.event.id} to ${result.deliveries.length} channel(s)`);
   });
-  events.command("list").description("List recorded events").option("--source <source>", "Filter by source").option("--type <type>", "Filter by type").option("--limit <n>", "Limit results", parseNumber).option("-j, --json", "Print JSON output", false).action(async (actionOptions, command) => {
+  const defaultListLimit = options.defaultEventListLimit ?? DEFAULT_EVENT_LIST_LIMIT;
+  events.command("list").description("List recorded events").option("--source <source>", "Filter by source").option("--type <type>", "Filter by type").option("--limit <n>", `Limit to the most recent <n> events (default ${defaultListLimit}; use 0 for all)`, parseNumber, defaultListLimit).option("-j, --json", "Print JSON output", false).action(async (actionOptions, command) => {
     let rows = await createClient(options).listEvents();
     if (actionOptions.source)
       rows = rows.filter((event) => event.source === actionOptions.source);
@@ -6965,14 +7384,16 @@ function registerEventCommands(program, options) {
     for (const event of rows)
       console.log(`${event.time}	${event.id}	${event.source}	${event.type}	${event.severity}`);
   });
-  events.command("replay").description("Replay recorded events").option("--id <id>", "Replay one event id").option("--source <source>", "Filter by source").option("--type <type>", "Filter by type").option("--dry-run", "Preview without delivery", false).option("-j, --json", "Print JSON output", false).action(async (actionOptions, command) => {
+  events.command("replay").description("Replay recorded events").option("--id <id>", "Replay one event id").option("--source <source>", "Filter by source").option("--type <type>", "Filter by type").option("--cursor <cursor>", "Opaque replay cursor from a previous page").option("--limit <n>", "Maximum events to replay", parseNumber).option("--dry-run", "Preview without delivery", false).option("-j, --json", "Print JSON output", false).action(async (actionOptions, command) => {
     const result = await createClient(options).replay({
       eventId: actionOptions.id,
       source: actionOptions.source,
       type: actionOptions.type,
+      cursor: actionOptions.cursor,
+      limit: actionOptions.limit,
       dryRun: actionOptions.dryRun
     });
-    print(result, wantsJson(actionOptions, command), `Replayed ${result.events.length} event(s), ${result.deliveries.length} delivery result(s)`);
+    print(result, wantsJson(actionOptions, command), replaySummary(result.events.length, result.deliveries.length, result.nextCursor));
   });
   return events;
 }
@@ -6990,6 +7411,10 @@ function collectValues(value, previous) {
   previous.push(value);
   return previous;
 }
+function replaySummary(events, deliveries, nextCursor) {
+  const suffix = nextCursor ? `, next cursor: ${nextCursor}` : "";
+  return `Replayed ${events} event(s), ${deliveries} delivery result(s)${suffix}`;
+}
 
 // src/cli/index.tsx
 import { render } from "ink";
@@ -8208,6 +8633,39 @@ function resolveTarget(options) {
     return "all";
   return "claude";
 }
+function parseLimit(value, fallback, max) {
+  const parsed = value ? parseInt(value, 10) : fallback;
+  if (!Number.isFinite(parsed) || parsed <= 0)
+    return fallback;
+  return Math.min(parsed, max);
+}
+function truncateText2(value, max = 96) {
+  const text = (value ?? "").replace(/\s+/g, " ").trim();
+  if (text.length <= max)
+    return text;
+  return `${text.slice(0, Math.max(0, max - 3))}...`;
+}
+function readmePreview(readme, max = 280) {
+  const blocks = readme.split(/\n\s*\n/).map((part) => part.trim()).filter(Boolean).filter((part) => !part.startsWith("#")).filter((part) => !part.startsWith("```")).filter((part) => !/^\[!\[/.test(part));
+  const preview = blocks[0] ?? readme.split(`
+`).map((line) => line.trim()).find((line) => line && !line.startsWith("#"));
+  return preview ? truncateText2(preview, max) : undefined;
+}
+function hookSummaryLine(hook, options = {}) {
+  const matcher = hook.matcher ? ` ${hook.matcher}` : "";
+  const description = options.verbose ? ` - ${truncateText2(hook.description, 110)}` : "";
+  return `  ${chalk2.cyan(hook.name.padEnd(17))} ${chalk2.dim(`[${hook.event}${matcher}]`)} ${chalk2.dim(hook.category)}${description}`;
+}
+function printDisclosureHint(hidden, detailCommand, options = {}) {
+  const rowControls = options.includeAll ? "--limit, --all, --verbose" : "--limit, --verbose";
+  if (hidden > 0) {
+    console.log(chalk2.dim(`
+  Showing a compact subset. ${hidden} more hidden; use ${rowControls}, or ${detailCommand}.`));
+  } else {
+    console.log(chalk2.dim(`
+  Use --verbose or ${detailCommand} for details.`));
+  }
+}
 function editDistance(a, b) {
   const m = a.length, n = b.length;
   const dp = Array.from({ length: m + 1 }, (_, i) => [i, ...Array(n).fill(0)]);
@@ -8417,8 +8875,9 @@ Installing hooks (${scope}, ${target})...
   console.log(chalk2.dim(`
 Registered in ${settingsFile}`));
 });
-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 registered hooks", false).option("-g, --global", "Check global settings", false).option("-p, --project", "Check project settings", false).option("-t, --target <target>", "Agent target: claude, gemini, codewith (default: claude)", "claude").option("-j, --json", "Output as JSON", 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 registered hooks", false).option("-g, --global", "Check global settings", false).option("-p, --project", "Check project settings", false).option("-t, --target <target>", "Agent target: claude, gemini, codewith (default: claude)", "claude").option("-n, --limit <n>", "Max rows to show in compact output", "20").option("--verbose", "Show descriptions and full detail columns", false).option("-j, --json", "Output as JSON", false).description("List available or installed hooks").action((options) => {
   const scope = resolveScope(options);
+  const limit = options.all ? Number.MAX_SAFE_INTEGER : parseLimit(options.limit, 20, 200);
   if (options.registered || options.installed) {
     const target = options.target === "gemini" ? "gemini" : options.target === "codewith" ? "codewith" : "claude";
     const registered = getRegisteredHooksForTarget(scope, target);
@@ -8433,13 +8892,18 @@ program2.command("list").alias("ls").option("-c, --category <category>", "Filter
       console.log(chalk2.dim(`No hooks registered (${scope}, ${target})`));
       return;
     }
+    const visible2 = registered.slice(0, limit);
     console.log(chalk2.bold(`
-Registered hooks \u2014 ${scope}/${target} (${registered.length}):
+Registered hooks \u2014 ${scope}/${target} (${registered.length}, showing ${visible2.length}):
 `));
-    for (const name of registered) {
+    for (const name of visible2) {
       const meta = getHook(name);
-      console.log(`  ${chalk2.cyan(name)} ${chalk2.dim(`[${meta?.event || "unknown"}]`)} - ${meta?.description || ""}`);
+      if (meta)
+        console.log(hookSummaryLine(meta, { verbose: options.verbose }));
+      else
+        console.log(`  ${chalk2.cyan(name)} ${chalk2.dim("[unknown]")}`);
     }
+    printDisclosureHint(registered.length - visible2.length, "hooks info <name>", { includeAll: true });
     return;
   }
   if (options.category) {
@@ -8458,12 +8922,13 @@ Registered hooks \u2014 ${scope}/${target} (${registered.length}):
       console.log(JSON.stringify(hooks));
       return;
     }
+    const visible2 = hooks.slice(0, limit);
     console.log(chalk2.bold(`
-${category} (${hooks.length}):
+${category} (${hooks.length}, showing ${visible2.length}):
 `));
-    for (const h of hooks) {
-      console.log(`  ${chalk2.cyan(h.name)} ${chalk2.dim(`[${h.event}]`)} - ${h.description}`);
-    }
+    for (const h of visible2)
+      console.log(hookSummaryLine(h, { verbose: options.verbose }));
+    printDisclosureHint(hooks.length - visible2.length, "hooks info <name>", { includeAll: true });
     return;
   }
   if (options.json) {
@@ -8474,19 +8939,15 @@ ${category} (${hooks.length}):
     console.log(JSON.stringify(result));
     return;
   }
+  const visible = HOOKS.slice(0, limit);
   console.log(chalk2.bold(`
-Available hooks (${HOOKS.length}):
+Available hooks (${HOOKS.length}, showing ${visible.length}):
 `));
-  for (const category of CATEGORIES) {
-    const hooks = getHooksByCategory(category);
-    console.log(chalk2.bold(`${category} (${hooks.length}):`));
-    for (const h of hooks) {
-      console.log(`  ${chalk2.cyan(h.name)} ${chalk2.dim(`[${h.event}]`)} - ${h.description}`);
-    }
-    console.log();
-  }
+  for (const h of visible)
+    console.log(hookSummaryLine(h, { verbose: options.verbose }));
+  printDisclosureHint(HOOKS.length - visible.length, "hooks info <name>", { includeAll: true });
 });
-program2.command("search").argument("<query>", "Search term").option("-j, --json", "Output as JSON", false).description("Search for hooks").action((query, options) => {
+program2.command("search").argument("<query>", "Search term").option("-n, --limit <n>", "Max rows to show in compact output", "10").option("--verbose", "Show descriptions for search results", false).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));
@@ -8496,13 +8957,14 @@ program2.command("search").argument("<query>", "Search term").option("-j, --json
     console.log(chalk2.dim(`No hooks found for "${query}"`));
     return;
   }
+  const limit = parseLimit(options.limit, 10, 100);
+  const visible = results.slice(0, limit);
   console.log(chalk2.bold(`
-Found ${results.length} hook(s):
+Found ${results.length} hook(s), showing ${visible.length}:
 `));
-  for (const h of results) {
-    console.log(`  ${chalk2.cyan(h.name)} ${chalk2.dim(`[${h.event}] [${h.category}]`)}`);
-    console.log(`    ${h.description}`);
-  }
+  for (const h of visible)
+    console.log(hookSummaryLine(h, { verbose: options.verbose }));
+  printDisclosureHint(results.length - visible.length, "hooks info <name>");
 });
 program2.command("remove").alias("rm").argument("<hook>", "Hook to remove").option("-g, --global", "Remove from global settings", false).option("-p, --project", "Remove from project settings", false).option("-t, --target <target>", "Agent target: claude, gemini, codewith, all (default: claude)", "claude").option("-j, --json", "Output as JSON", false).description("Remove an installed hook").action((hook, options) => {
   const scope = resolveScope(options);
@@ -8698,7 +9160,7 @@ Updating hooks...
     }
   }
 });
-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) => {
+program2.command("docs").argument("[hook]", "Hook name (shows general docs if omitted)").option("--verbose", "Print full hook README content", false).option("-j, --json", "Output as JSON", false).description("Show documentation for hooks").action((hook, options) => {
   if (hook) {
     const meta = getHook(hook);
     if (!meta) {
@@ -8733,13 +9195,23 @@ ${meta.displayName} v${meta.version}
     console.log(`    hooks install ${meta.name}            # global`);
     console.log(`    hooks install ${meta.name} --project   # project only`);
     console.log();
-    if (readme) {
+    if (readme && options.verbose) {
       console.log(chalk2.bold(`  README:
 `));
       for (const line of readme.split(`
 `)) {
         console.log(`    ${line}`);
       }
+    } else if (readme) {
+      const preview = readmePreview(readme);
+      if (preview) {
+        console.log(chalk2.bold(`  README Preview:
+`));
+        console.log(`    ${preview}
+`);
+      }
+      console.log(chalk2.dim(`  README has ${readme.split(`
+`).length} lines. Use hooks docs ${meta.name} --verbose for the full README, or --json for machine-readable output.`));
     }
     return;
   }
@@ -8816,8 +9288,9 @@ ${meta.displayName} v${meta.version}
   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(`    hooks docs <name>              Compact hook docs`);
+  console.log(`    hooks docs <name> --verbose    Full hook README`);
+  console.log(`    hooks docs --json              Machine-readable documentation`);
   console.log();
 });
 program2.command("upgrade").option("-c, --check", "Check for updates without installing", false).option("-j, --json", "Output as JSON", false).description("Update the @hasna/hooks package to the latest version").action(async (options) => {
@@ -8963,11 +9436,12 @@ logCmd.command("list").description("List hook events").option("--hook <name>", "
 `));
   for (const row of rows) {
     const ts = row.timestamp.slice(0, 19).replace("T", " ");
-    const err = row.error ? chalk2.red(` ERR: ${row.error.slice(0, 60)}`) : "";
+    const err = row.error ? chalk2.red(` ERR: ${truncateText2(row.error, 60)}`) : "";
     const tool = row.tool_name ? chalk2.dim(` [${row.tool_name}]`) : "";
     console.log(`  ${chalk2.dim(ts)}  ${chalk2.cyan(row.hook_name.padEnd(14))}${tool}${err}`);
   }
-  console.log();
+  console.log(chalk2.dim(`
+  Compact rows shown. Use --json for full event records or --limit <n> to change row count.`));
 });
 logCmd.command("search <text>").description("Search hook events by tool_input or error text").option("-n, --limit <n>", "Number of rows to show", "50").option("-j, --json", "Output as JSON", false).action(async (text, options) => {
   const { getDb: getDb2 } = await Promise.resolve().then(() => (init_db(), exports_db));
@@ -8988,10 +9462,11 @@ logCmd.command("search <text>").description("Search hook events by tool_input or
 `));
   for (const row of rows) {
     const ts = row.timestamp.slice(0, 19).replace("T", " ");
-    const snippet = (row.tool_input || row.error || "").slice(0, 80);
+    const snippet = truncateText2(row.tool_input || row.error || "", 80);
     console.log(`  ${chalk2.dim(ts)}  ${chalk2.cyan(row.hook_name.padEnd(14))}  ${chalk2.dim(snippet)}`);
   }
-  console.log();
+  console.log(chalk2.dim(`
+  Compact rows shown. Use --json for full event records or --limit <n> to change row count.`));
 });
 logCmd.command("tail").description("Show most recent hook events").option("-n <n>", "Number of rows", "20").option("-j, --json", "Output as JSON", false).action(async (options) => {
   const { getDb: getDb2 } = await Promise.resolve().then(() => (init_db(), exports_db));
@@ -9011,11 +9486,12 @@ logCmd.command("tail").description("Show most recent hook events").option("-n <n
 `));
   for (const row of rows) {
     const ts = row.timestamp.slice(0, 19).replace("T", " ");
-    const err = row.error ? chalk2.red(` \u2717 ${row.error.slice(0, 60)}`) : "";
+    const err = row.error ? chalk2.red(` \u2717 ${truncateText2(row.error, 60)}`) : "";
     const tool = row.tool_name ? chalk2.dim(` [${row.tool_name}]`) : "";
     console.log(`  ${chalk2.dim(ts)}  ${chalk2.cyan(row.hook_name.padEnd(14))}${tool}${err}`);
   }
-  console.log();
+  console.log(chalk2.dim(`
+  Compact rows shown. Use --json for full event records or -n <n> to change row count.`));
 });
 logCmd.command("errors").description("Show hook events that contain errors").option("--since <duration>", "Only show errors since this duration (e.g. 1h, 30m, 7d)", "24h").option("-n, --limit <n>", "Number of rows to show", "50").option("-j, --json", "Output as JSON", false).action(async (options) => {
   const { getDb: getDb2 } = await Promise.resolve().then(() => (init_db(), exports_db));
@@ -9054,9 +9530,10 @@ logCmd.command("errors").description("Show hook events that contain errors").opt
 `));
   for (const row of rows) {
     const ts = row.timestamp.slice(0, 19).replace("T", " ");
-    console.log(`  ${chalk2.dim(ts)}  ${chalk2.cyan(row.hook_name.padEnd(14))}  ${chalk2.red(row.error.slice(0, 100))}`);
+    console.log(`  ${chalk2.dim(ts)}  ${chalk2.cyan(row.hook_name.padEnd(14))}  ${chalk2.red(truncateText2(row.error, 100))}`);
   }
-  console.log();
+  console.log(chalk2.dim(`
+  Compact rows shown. Use --json for full event records or --limit <n> to change row count.`));
 });
 logCmd.command("clear").description("Delete hook event logs").option("--hook <name>", "Only delete events for this hook").option("-y, --yes", "Skip confirmation prompt", false).action(async (options) => {
   const { getDb: getDb2 } = await Promise.resolve().then(() => (init_db(), exports_db));